RESEARCH ENVIRONMENT

Powerful notebooks
attached to our
massive data
repository

Our data repository is preformatted
and ready to go. Skip expensive
and tedious data processing and
get to work.

Table of Content

Key Concepts

Key Concepts > Getting Started

Introduction

The Research Environment is a Jupyter notebook -based, interactive commandline environment where you can access our data through the QuantBook class. The environment supports both Python and C#. If you use Python, you can import code from the code files in your project into the Research Environment to aid development.

Before you run backtests, we recommend testing your hypothesis in the Research Environment. It's easier to perform data analysis and produce plots in the Research Environment than in a backtest.

Before backtesting or live trading with machine learning models, you may find it beneficial to train them in the Research Environment, save them in the ObjectStore, and then load them from the ObjectStore into the backtesting and live trading environment

In the Research Environment, you can also use the QuantConnect API to import your backtest results for further analysis.

Example

The following snippet demonstrates how to use the Research Environment to plot the price and Bollinger Bands of the S&P 500 index ETF, SPY:

The following snippet demonstrates how to use the Research Environment to print the price of the S&P 500 index ETF, SPY:

// Load the required assembly files and data types
#load "../Initialize.csx"
#load "../QuantConnect.csx"
using QuantConnect;
using QuantConnect.Data;
using QuantConnect.Algorithm;
using QuantConnect.Research;

// Create a QuantBook
var qb = new QuantBook();

// Create a security subscription
var symbol = qb.AddEquity("SPY").Symbol;

// Request some historical data
var history = qb.History(symbol, 70, Resolution.Daily);

foreach (var tradeBar in history)
{
    Console.WriteLine($"{tradeBar.EndTime} :: {tradeBar.ToString()}");
}

# Create a QuantBook
qb = QuantBook()

# Create a security subscription
spy = qb.AddEquity("SPY")

# Request some historical data
history = qb.History(qb.Securities.Keys, 360, Resolution.Daily)

# Calculate the Bollinger Bands
bbdf = qb.Indicator(BollingerBands(30, 2), spy.Symbol, 360, Resolution.Daily)

# Plot the data
bbdf.drop('standarddeviation', 1).plot()

Open Notebooks

Each new project you create contains a notebook file by default. Follow these steps to open the notebook:

1. Open the project .
2. In the right navigation menu, click the Explorer icon.
3. In the Explorer panel, expand the Workspace (Workspace) section.
4. Click the Research.ipynb research.ipynb file.

Run Notebook Cells

Notebooks are a collection of cells where you can execute code snippets or write MarkDown.

The following describes some helpful keyboard shortcuts to speed up your research:

Stop Nodes

You need stop node permissions to stop research nodes in the cloud.

Follow these steps to stop a research node:

1. Open the project .
2. In the right navigation menu, click the Resources icon.
3. Click the stop button next to the research node you want to stop.

Add Notebooks

Follow these steps to add notebook files to a project:

1. Open the project .
2. In the right navigation menu, click the Explorer icon.
3. In the Explorer panel, expand the Workspace (Workspace) section.
4. Click the New File icon.
5. Enter fileName .ipynb .
6. Press Enter .

Rename Notebooks

Follow these steps to rename a notebook in a project:

1. Open the project .
2. In the right navigation menu, click the Explorer icon.
3. In the Explorer panel, right-click the notebook you want to rename and then click Rename .
4. Enter the new name and then press Enter .

Delete Notebooks

Follow these steps to delete a notebook in a project:

1. Open the project .
2. In the right navigation menu, click the Explorer icon.
3. In the Explorer panel, right-click the notebook you want to delete and then click Delete Permanently .
4. Click Delete .

Learn Jupyter

The following table lists some helpful resources to learn Jupyter:

Key Concepts > Research Engine

Introduction

The Research Environment is a Jupyter notebook -based, interactive commandline environment where you can access our data through the QuantBook class. The environment supports both Python and C#. If you use Python, you can import code from the code files in your project into the Research Environment to aid development.

Before you run backtests, we recommend testing your hypothesis in the Research Environment. It's easier to perform data analysis and produce plots in the Research Environment than in a backtest.

Before backtesting or live trading with machine learning models, you may find it beneficial to train them in the Research Environment, save them in the ObjectStore, and then load them from the ObjectStore into the backtesting and live trading environment

In the Research Environment, you can also use the QuantConnect API to import your backtest results for further analysis.

Batch vs Stream Analysis

The backtesting environment is an event-based simulation of the market. Backtests aim to provide an accurate representation of whether a strategy would have performed well in the past, but they are generally slow and aren't the most efficient way to test the foundational ideas behind strategies. You should only use backtests to verify an idea after you have already tested it with statistical analysis.

The Research Environment lets you build a strategy by starting with a central hypothesis about the market. For example, you might hypothesize that an increase in sunshine hours will increase the production of oranges, which will lead to an increase in the supply of oranges and a decrease in the price of Orange Juice Futures. You can attempt to confirm this working hypothesis by analyzing weather data, production of oranges data, and the price of Orange Juice futures. If the hypothesis is confirmed with a degree of statistical significance, you can be confident in the hypothesis and translate it into an algorithm you can backtest.

Jupyter Notebooks

Jupyter notebooks support interactive data science and scientific computing across various programming languages. We carry on that philosophy by providing an environment for you to perform exploratory research and brainstorm new ideas for algorithms. A Jupyter notebook installed in QuantConnect allows you to directly explore the massive amounts of data that is available in the Dataset Market and analyze it with python or C# commands. We call this exploratory notebook environment the Research Environment.

Open Notebooks

To open a notebook, open one of the .ipynb files in your cloud projects or see Running Local Research Environment .

Execute Code

The notebook allows you to run code in a safe and disposable environment. It's composed of independent cells where you can write, edit, and execute code. The notebooks support Python, C#, and Markdown code.

Keyboard Shortcuts

The following table describes some useful keyboard shortcuts:

Terminate Research Sessions

If you use the Research Environment in QuantConnect Cloud, to terminate a research session, stop the research node in the Resources panel . If you use the local Research Environment, see Managing Kernels and Terminals in the JupyterLab documentation.

Your Research and LEAN

To analyze data in a research notebook, create an instance of the QuantBook class. QuantBook is a wrapper on QCAlgorithm , which means QuantBook allows you to access all the methods available to QCAlgorithm and some additional methods. The following table describes the helper methods of the QuantBook class that aren't available in the QCAlgorithm class:

QuantBook gives you access to the vast amounts of data in the Dataset Market. Similar to backtesting, you can access that data using history calls. You can also create indicators, consolidate data, and access charting features. However, keep in mind that event-driven features available in backtesting, like universe selection and OnData events, are not available in research. After you analyze a dataset in the Research Environment, you can easily transfer the logic to the backtesting environment. For example, consider the following code in the Research Environment:

// Initialize QuantBook
var qb = new QuantBook();

// Subscribe to SPY data with QuantBook
var symbol = qb.AddEquity("SPY").Symbol;

// Make history call with QuantBook
var history = qb.History(symbol, TimeSpan.FromDays(10), Resolution.Daily);

# Initialize QuantBook
qb = QuantBook()

# Subscribe to SPY data with QuantBook
symbol = qb.AddEquity("SPY").Symbol

# Make history call with QuantBook
history = qb.History(symbol, timedelta(days=10), Resolution.Daily)

To use the preceding code in a backtest, replace QuantBook() new QuantBook() with self this .

public override void Initialize()
{
    // Set qb to instance of QCAlgorithm
    var qb = this;
    
    // Subscribe to SPY data with QCAlgorithm
    var symbol = qb.AddEquity("SPY").Symbol;
    
    // Make history call with QCAlgorithm
    var history = qb.History(symbol, TimeSpan.FromDays(10), Resolution.Daily);
}

def Initialize(self) -> None:

    # Set qb to instance of QCAlgorithm
    qb = self
    
    # Subscribe to SPY data with QCAlgorithm
    symbol = qb.AddEquity("SPY").Symbol
    
    # Make history call with QCAlgorithm
    history = qb.History(symbol, timedelta(days=10), Resolution.Daily)

Import Project Code

To import code from your code files to your Research Environment session, use Python.

One of the drawbacks of using the Research Environment you may encounter is the need to rewrite code you've already written in a file in the backtesting environment. Instead of rewriting the code, you can import the methods from the backtesting environment into the Research Environment to reduce development time. For example, say you have the following helpers.py file in your project:

def Add(a, b): 
   return a+b

To import the preceding method into your research notebook, use the import statement.

from helpers import Add

# reuse method from helpers.py
Add(3, 4)

If you adjust the file that you import, restart the Research Environment session to import the latest version of the file. To restart the Research Environment, stop the research node and then open the notebook again.

Initialization

Introduction

Before you request and manipulate historical data in the Research Environment, you should set the notebook dates, add data subscriptions, and set the time zone.

Set Dates

The start date of your QuantBook determines the latest date of data you get from history requests . By default, the start date is the current day. To change the start date, call the SetStartDate method.

qb.SetStartDate(2022, 1, 1);

qb.SetStartDate(2022, 1, 1)

The end date of your QuantBook should be greater than the end date. By default, the start date is the current day. To change the end date, call the SetEndDate method.

qb.SetEndDate(2022, 8, 15);

qb.SetEndDate(2022, 8, 15)

Add Data

You can subscribe to asset, fundamental, alternative, and custom data. The Dataset Market provides 400TB of data that you can easily import into your notebooks.

Asset Data

To subscribe to asset data, call one of the asset subscription methods like AddEquity or AddForex . Each asset class has its own method to create subscriptions. For more information about how to create subscriptions for each asset class, see the Create Subscriptions section of an asset class in the Datasets chapter.

qb.AddEquity("AAPL"); // Add Apple 1 minute bars (minute by default)
qb.AddForex("EURUSD", Resolution.Second); // Add EURUSD 1 second bars

qb.AddEquity("SPY")  # Add Apple 1 minute bars (minute by default)
qb.AddForex("EURUSD", Resolution.Second) # Add EURUSD 1 second bars

Alternative Data

To add alternative datasets to your notebooks, call the AddData method. For a full example, see Alternative Data .

Custom Data

To add custom data to your notebooks, call the AddData method. For more information about custom data, see Custom Data .

Limitations

There is no official limit to how much data you can add to your notebooks, but there are practical resource limitations. Each security subscription requires about 5MB of RAM, so larger machines let you request more data. For more information about our cloud nodes, see Research Nodes .

Set Time Zone

The notebook time zone determines which time zone the DateTime datetime objects are in when you make a history request based on a defined period of time. When your history request returns a DataFrame , the timestamps in the DataFrame are based on the data time zone . When your history request returns a TradeBars , QuoteBars , Ticks , or Slice object, the Time properties of these objects are based on the notebook time zone, but the EndTime properties of the individual TradeBar , QuoteBar , and Tick objects are based on the data time zone.

The default time zone is Eastern Time (ET), which is UTC-4 in summer and UTC-5 in winter. To set a different time zone, call the SetTimeZone method. This method accepts either a string following the IANA Time Zone database convention or a NodaTime .DateTimeZone object. If you pass a string, the method converts it to a NodaTime.DateTimeZone object. The TimeZones class provides the following helper attributes to create NodaTime.DateTimeZone objects:

SetTimeZone("Europe/London");
qb.SetTimeZone(NodaTime.DateTimeZone.Utc);
qb.SetTimeZone(TimeZones.Chicago);

qb.SetTimeZone("Europe/London")
qb.SetTimeZone(TimeZones.Chicago)

Datasets

Datasets > Key Concepts

Introduction

You can access most of the data from the Dataset Market in the Research Environment. The data includes Equity, Crypto, Forex, and derivative data going back as far as 1998. Similar to backtesting, to access the data, create a security subscription and then make a history request.

Key History Concepts

The historical data API has many different options to give you the greatest flexibility in how to apply it to your algorithm.

Time Period Options

You can request historical data based on a trailing number of bars, a trailing period of time, or a defined period of time. If you request data in a defined period of time, the DateTime datetime objects you provide are based in the notebook time zone .

Return Formats

Each asset class supports slightly different data formats. When you make a history request, consider what data returns. Depending on how you request the data, history requests return a specific data type. For example, if you don't provide Symbol objects, you get Slice objects that contain all of the assets you created subscriptions for in the notebook.

The most popular return type is a DataFrame . If you request a DataFrame , LEAN unpacks the data from Slice objects to populate the DataFrame . If you intend to use the data in the DataFrame to create TradeBar or QuoteBar objects, request that the history request returns the data type you need. Otherwise, LEAN will waste computational resources populating the DataFrame .

Time Index

When your history request returns a DataFrame , the timestamps in the DataFrame are based on the data time zone . When your history request returns a TradeBars , QuoteBars , Ticks , or Slice object, the Time properties of these objects are based on the notebook time zone, but the EndTime properties of the individual TradeBar , QuoteBar , and Tick objects are based on the data time zone data time zone . The EndTime is the end of the sampling period and when the data is actually available. For daily US Equity data, this results in data points appearing on Saturday and skipping Monday.

Request Data

The simplest form of history request is for a known set of Symbol objects. History requests return slightly different data depending on the overload you call. The data that returns is in ascending order from oldest to newest.

Single Symbol History Requests

To request history for a single asset, pass the asset Symbol to the History method. The return type of the method call depends on the history request [Type] <Type> . The following table describes the return type of each request [Type] <Type> :

Each row of the DataFrame represents the prices at a point in time. Each column of the DataFrame is a property of that price data (for example, open, high, low, and close (OHLC)). If you request a DataFrame object and pass TradeBar as the first argument, the DataFrame that returns only contains the OHLC and volume columns. If you request a DataFrame object and pass QuoteBar as the first argument, the DataFrame that returns contains the OHLC of the bid and ask and it contains OHLC columns, which are the respective means of the bid and ask OHLC values. If you request a DataFrame and don't pass TradeBar or QuoteBar as the first arugment, the DataFrame that returns contains columns for all of the data that's available for the given resolution.

# EXAMPLE 1: Requesting By Bar Count: 5 bars at the security resolution:
vix_symbol = qb.AddData(CBOE, "VIX", Resolution.Daily).Symbol
cboe_data = qb.History[CBOE](vix_symbol, 5)

btc_symbol = qb.AddCrypto("BTCUSD", Resolution.Minute).Symbol
trade_bars = qb.History[TradeBar](btc_symbol, 5)
quote_bars = qb.History[QuoteBar](btc_symbol, 5)
trade_bars_df = qb.History(TradeBar, btc_symbol, 5)
quote_bars_df = qb.History(QuoteBar, btc_symbol, 5)
df = qb.History(btc_symbol, 5)   # Includes trade and quote data

// EXAMPLE 1: Requesting By Bar Count: 5 bars at the security resolution:
var vixSymbol = qb.AddData<CBOE>("VIX", Resolution.Daily).Symbol;
var cboeData = qb.History<CBOE>(vixSymbol, 5);

var btcSymbol = qb.AddCrypto("BTCUSD", Resolution.Minute).Symbol;
var tradeBars = qb.History<TradeBar>(btcSymbol, 5);
var quoteBars = qb.History<QuoteBar>(btcSymbol, 5);
var tradeBars2 = qb.History(btcSymbol, 5);

# EXAMPLE 2: Requesting By Bar Count: 5 bars with a specific resolution:
trade_bars = qb.History[TradeBar](btc_symbol, 5, Resolution.Daily)
quote_bars = qb.History[QuoteBar](btc_symbol, 5, Resolution.Minute)
trade_bars_df = qb.History(TradeBar, btc_symbol, 5, Resolution.Minute)
quote_bars_df = qb.History(QuoteBar, btc_symbol, 5, Resolution.Minute)
df = qb.History(btc_symbol, 5, Resolution.Minute)  # Includes trade and quote data

// EXAMPLE 2: Requesting By Bar Count: 5 bars with a specific resolution:
var tradeBars = qb.History<TradeBar>(btcSymbol, 5, Resolution.Daily);
var quoteBars = qb.History<QuoteBar>(btcSymbol, 5, Resolution.Minute);
var tradeBars2 = qb.History(btcSymbol, 5, Resolution.Minute);

# EXAMPLE 3: Requesting By a Trailing Period: 3 days of data at the security resolution: 
eth_symbol = qb.AddCrypto('ETHUSD', Resolution.Tick).Symbol
ticks = qb.History[Tick](eth_symbol, timedelta(days=3))
ticks_df = qb.History(eth_symbol, timedelta(days=3))

vix_data = qb.History[CBOE](vix_symbol, timedelta(days=3)) 
trade_bars = qb.History[TradeBar](btc_symbol, timedelta(days=3)) 
quote_bars = qb.History[QuoteBar](btc_symbol, timedelta(days=3))
trade_bars_df = qb.History(TradeBar, btc_symbol, timedelta(days=3))
quote_bars_df = qb.History(QuoteBar, btc_symbol, timedelta(days=3))
df = qb.History(btc_symbol, timedelta(days=3))  # Includes trade and quote data

// EXAMPLE 3: Requesting By a Trailing Period: 3 days of data at the security resolution:
var ethSymbol = qb.AddCrypto("ETHUSD", Resolution.Tick).Symbol;
var ticks = qb.History<Tick>(ethSymbol, TimeSpan.FromDays(3));

var cboeData = qb.History<CBOE>(vixSymbol, TimeSpan.FromDays(3));
var tradeBars = qb.History<TradeBar>(btcSymbol, TimeSpan.FromDays(3));
var quoteBars = qb.History<QuoteBar>(btcSymbol, TimeSpan.FromDays(3));
var tradeBars2 = qb.History(btcSymbol, TimeSpan.FromDays(3));

# EXAMPLE 4: Requesting By a Trailing Period: 3 days of data with a specific resolution: 
trade_bars = qb.History[TradeBar](btc_symbol, timedelta(days=3), Resolution.Daily) 
quote_bars = qb.History[QuoteBar](btc_symbol, timedelta(days=3), Resolution.Minute)
ticks = qb.History[Tick](eth_symbol, timedelta(days=3), Resolution.Tick)

trade_bars_df = qb.History(TradeBar, btc_symbol, timedelta(days=3), Resolution.Daily)
quote_bars_df = qb.History(QuoteBar, btc_symbol, timedelta(days=3), Resolution.Minute)
ticks_df = qb.History(eth_symbol, timedelta(days=3), Resolution.Tick)
df = qb.History(btc_symbol, timedelta(days=3), Resolution.Hour)  # Includes trade and quote data

# Important Note: Period history requests are relative to "now" notebook time.

// EXAMPLE 4: Requesting By a Trailing Period: 3 days of data with a specific resolution:
var tradeBars = qb.History<TradeBar>(btcSymbol, TimeSpan.FromDays(3), Resolution.Daily);
var quoteBars = qb.History<QuoteBar>(btcSymbol, TimeSpan.FromDays(3), Resolution.Minute);
var ticks = qb.History<Tick>(ethSymbol, TimeSpan.FromDays(3), Resolution.Tick);
var tradeBars2 = qb.History(btcSymbol, TimeSpan.FromDays(3), Resolution.Minute);

# EXAMPLE 5: Requesting By a Defined Period: 3 days of data at the security resolution: 
start_time = datetime(2022, 1, 1)
end_time = datetime(2022, 1, 4)

vix_data = qb.History[CBOE](vix_symbol, start_time, end_time) 
trade_bars = qb.History[TradeBar](btc_symbol, start_time, end_time) 
quote_bars = qb.History[QuoteBar](btc_symbol, start_time, end_time)
ticks = qb.History[Tick](eth_symbol, start_time, end_time)

trade_bars_df = qb.History(TradeBar, btc_symbol, start_time, end_time)
quote_bars_df = qb.History(QuoteBar, btc_symbol, start_time, end_time)
ticks_df = qb.History(Tick, eth_symbol, start_time, end_time)
df = qb.History(btc_symbol, start_time, end_time)  # Includes trade and quote data

// EXAMPLE 5: Requesting By a Defined Period: 3 specific days of data at the security resolution:
var startTime = new DateTime(2022, 1, 1);
var endTime = new DateTime(2022, 1, 4);

var cboeData = qb.History<CBOE>(vixSymbol, startTime, endTime);
var tradeBars = qb.History<TradeBar>(btcSymbol, startTime, endTime);
var quoteBars = qb.History<QuoteBar>(btcSymbol, startTime, endTime);
var ticks = qb.History<Tick>(ethSymbol, startTime, endTime);
var tradeBars2 = qb.History(btcSymbol, startTime, endTime);

# EXAMPLE 6: Requesting By a Defined Period: 3 days of data with a specific resolution: 
trade_bars = qb.History[TradeBar](btc_symbol, start_time, end_time, Resolution.Daily) 
quote_bars = qb.History[QuoteBar](btc_symbol, start_time, end_time, Resolution.Minute)
ticks = qb.History[Tick](eth_symbol, start_time, end_time, Resolution.Tick)

trade_bars_df = qb.History(TradeBar, btc_symbol, start_time, end_time, Resolution.Daily)
quote_bars_df = qb.History(QuoteBar, btc_symbol, start_time, end_time, Resolution.Minute)
ticks_df = qb.History(eth_symbol, start_time, end_time, Resolution.Tick)
df = qb.History(btc_symbol, start_time, end_time, Resolution.Hour)  # Includes trade and quote data

// EXAMPLE 6: Requesting By a Defined Period: 3 days of data with a specific resolution:
var tradeBars = qb.History<TradeBar>(btcSymbol, startTime, endTime, Resolution.Daily);
var quoteBars = qb.History<QuoteBar>(btcSymbol, startTime, endTime, Resolution.Minute);
var ticks = qb.History<Tick>(ethSymbol, startTime, endTime, Resolution.Tick);
var tradeBars2 = qb.History(btcSymbol, startTime, endTime, Resolution.Minute);

Multiple Symbol History Requests

To request history for multiple symbols at a time, pass an array of Symbol objects to the same API methods shown in the preceding section. The return type of the method call depends on the history request [Type] <Type> . The following table describes the return type of each request [Type] <Type> :

The Slice return type provides a container that supports all data types. For example, a history request for Forex QuoteBars and Equity TradeBars has the Forex data under slices.QuoteBars and the Equity data under slices.Bars .

# EXAMPLE 7: Requesting By Bar Count for Multiple Symbols: 2 bars at the security resolution:
vix = qb.AddData[CBOE]("VIX", Resolution.Daily).Symbol
v3m = qb.AddData[CBOE]("VIX3M", Resolution.Daily).Symbol
cboe_data = qb.History[CBOE]([vix, v3m], 2)

ibm = qb.AddEquity("IBM", Resolution.Minute).Symbol
aapl = qb.AddEquity("AAPL", Resolution.Minute).Symbol
trade_bars_list = qb.History[TradeBar]([ibm, aapl], 2)
quote_bars_list = qb.History[QuoteBar]([ibm, aapl], 2)

trade_bars_df = qb.History(TradeBar, [ibm, aapl], 2)
quote_bars_df = qb.History(QuoteBar, [ibm, aapl], 2)
df = qb.History([ibm, aapl], 2)  # Includes trade and quote data

// EXAMPLE 7: Requesting By Bar Count for Multiple Symbols: 2 bars at the security resolution:
var vixSymbol = qb.AddData<CBOE>("VIX", Resolution.Daily).Symbol;
var v3mSymbol = qb.AddData<CBOE>("VIX3m", Resolution.Daily).Symbol;
var cboeData = qb.History<CBOE>(new[] { vix, v3m }, 2);

var ibm = qb.AddEquity("IBM", Resolution.Minute).Symbol;
var aapl = qb.AddEquity("AAPL", Resolution.Minute).Symbol;
var tradeBarsList = qb.History<TradeBar>(new[] { ibm, aapl }, 2);
var quoteBarsList = qb.History<QuoteBar>(new[] { ibm, aapl }, 2);

# EXAMPLE 8: Requesting By Bar Count for Multiple Symbols: 5 bars with a specific resolution:
trade_bars_list = qb.History[TradeBar]([ibm, aapl], 5, Resolution.Daily)
quote_bars_list = qb.History[QuoteBar]([ibm, aapl], 5, Resolution.Minute)

trade_bars_df = qb.History(TradeBar, [ibm, aapl], 5, Resolution.Daily)
quote_bars_df = qb.History(QuoteBar, [ibm, aapl], 5, Resolution.Minute)
df = qb.History([ibm, aapl], 5, Resolution.Daily)  # Includes trade data only. No quote for daily equity data

// EXAMPLE 8: Requesting By Bar Count for Multiple Symbols: 5 bars with a specific resolution:
var tradeBarsList = qb.History<TradeBar>(new[] { ibm, aapl }, 5, Resolution.Minute);
var quoteBarsList = qb.History<QuoteBar>(new[] { ibm, aapl }, 5, Resolution.Minute);

# EXAMPLE 9: Requesting By Trailing Period: 3 days of data at the security resolution: 
ticks = qb.History[Tick]([eth_symbol], timedelta(days=3))

trade_bars = qb.History[TradeBar]([btc_symbol], timedelta(days=3)) 
quote_bars = qb.History[QuoteBar]([btc_symbol], timedelta(days=3))
trade_bars_df = qb.History(TradeBar, [btc_symbol], timedelta(days=3))
quote_bars_df = qb.History(QuoteBar, [btc_symbol], timedelta(days=3))
df = qb.History([btc_symbol], timedelta(days=3))  # Includes trade and quote data 

// EXAMPLE 9: Requesting By Trailing Period: 3 days of data at the security resolution:
var ticks = qb.History<Tick>(new[] {ethSymbol}, TimeSpan.FromDays(3));

var tradeBars = qb.History<TradeBar>(new[] {btcSymbol}, TimeSpan.FromDays(3));
var quoteBars = qb.History<QuoteBar>(new[] {btcSymbol}, TimeSpan.FromDays(3));
var tradeBars2 = qb.History(new[] {btcSymbol}, TimeSpan.FromDays(3));

# EXAMPLE 10: Requesting By Defined Period: 3 days of data at the security resolution: 
trade_bars = qb.History[TradeBar]([btc_symbol], start_time, end_time) 
quote_bars = qb.History[QuoteBar]([btc_symbol], start_time, end_time)
ticks = qb.History[Tick]([eth_symbol], start_time, end_time)
trade_bars_df = qb.History(TradeBar, btc_symbol, start_time, end_time)
quote_bars_df = qb.History(QuoteBar, btc_symbol, start_time, end_time)
ticks_df = qb.History(Tick, eth_symbol, start_time, end_time)
df = qb.History([btc_symbol], start_time, end_time)  # Includes trade and quote data

// EXAMPLE 10: Requesting By Defined Period: 3 days of data at the security resolution:
var tradeBars = qb.History<TradeBar>(new[] {btcSymbol}, startTime, endTime);
var quoteBars = qb.History<QuoteBar>(new[] {btcSymbol}, startTime, endTime);
var ticks = qb.History<Tick>(new[] {ethSymbol}, startTime, endTime);
var tradeBars2 = qb.History(new[] {btcSymbol}, startTime, endTime);

All Symbol History Requests

You can request history for all the securities you have created subscriptions for in your notebook session. The parameters are very similar to other history method calls, but the return type is an array of Slice objects. The Slice object holds all of the results in a sorted enumerable collection that you can iterate over with a loop.

# EXAMPLE 11: Requesting 5 bars for all securities at their respective resolution:

# Create subscriptions
qb.AddEquity("IBM", Resolution.Daily)
qb.AddEquity("AAPL", Resolution.Daily)

# Request history data and enumerate results
slices = qb.History(5)
for s in slices:
    print(str(s.Time) + " AAPL:" + str(s.Bars["AAPL"].Close) + " IBM:" + str(s.Bars["IBM"].Close))

// EXAMPLE 11: Requesting 5 bars for all securities at their respective resolution:

// Set up the universe
qb.AddEquity("IBM", Resolution.Daily);
qb.AddEquity("AAPL", Resolution.Daily);

// Request history data and enumerate results:
var slices = qb.History(5);
foreach (var s in slices) {
    var aaplClose = s.Bars["AAPL"].Close;
    var ibmClose = s.Bars["IBM"].Close;
    Console.WriteLine($"{s.Time} AAPL: {aaplClose} IBM: {ibmClose}");
}

# EXAMPLE 12: Requesting 5 minutes for all securities:

slices = qb.History(timedelta(minutes=5), Resolution.Minute)
for s in slices:
    print(str(s.Time) + " AAPL:" + str(s.Bars["AAPL"].Close) + " IBM:" + str(s.Bars["IBM"].Close))

# timedelta history requests are relative to "now" in notebook Time. If you request this data at 16:05, it returns an empty array because the market is closed.

// EXAMPLE 12: Requesting 24 hours of hourly data for all securities:

var slices = qb.History(TimeSpan.FromHours(24), Resolution.Hour);
foreach (var s in slices) {
    var aaplClose = s.Bars["AAPL"].Close;
    var ibmClose = s.Bars["IBM"].Close;
    Console.WriteLine($"{s.Time} AAPL: {aaplClose} IBM: {ibmClose}");
}

// TimeSpan history requests are relative to "now" in notebook Time.

Assumed Default Values

The following table describes the assumptions of the History API:

Additional Options

The History method accepts the following additional arguments:

future = qb.AddFuture(Futures.Currencies.BTC)
history = qb.History(
    tickers=[future.Symbol], 
    start=qb.Time - timedelta(days=15), 
    end=qb.Time, 
    resolution=Resolution.Minute, 
    fillForward=False, 
    extendedMarketHours=False, 
    dataMappingMode=DataMappingMode.OpenInterest, 
    dataNormalizationMode=DataNormalizationMode.Raw, 
    contractDepthOffset=0)

var future = qb.AddFuture(Futures.Currencies.BTC);
var history = qb.History(
    symbols: new[] {future.Symbol}, 
    start: qb.Time - TimeSpan.FromDays(15),
    end: qb.Time,
    resolution: Resolution.Minute,
    fillForward: false,
    extendedMarketHours: false,
    dataMappingMode: DataMappingMode.OpenInterest,
    dataNormalizationMode: DataNormalizationMode.Raw,
    contractDepthOffset: 0);

Resolutions

Resolution is the duration of time that's used to sample a data source. The Resolution enumeration has the following members:

The default resolution for market data is Minute . To set the resolution for a security, pass the resolution argument when you create the security subscription.

qb.AddEquity("SPY", Resolution.Daily);

qb.AddEquity("SPY", Resolution.Daily)

When you request historical data, the History method uses the resolution of your security subscription. To get historical data with a different resolution, pass a resolution argument to the History method.

history = qb.History(spy, 10, Resolution.Minute)

var history = qb.History(spy, 10, Resolution.Minute);

Markets

The datasets integrated into the Dataset Market cover many markets. The Market enumeration has the following members:

LEAN can usually determine the correct market based on the ticker you provide when you create the security subscription. To manually set the market for a security, pass a market argument when you create the security subscription.

qb.AddEquity("SPY", market: Market.USA);

qb.AddEquity("SPY", market=Market.USA)

Fill Forward

Fill forward means if there is no data point for the current sample, LEAN uses the previous data point. Fill forward is the default data setting. To disable fill forward for a security, set the fillForward argument to false when you create the security subscription.

qb.AddEquity("SPY", fillForward: false);

qb.AddEquity("SPY", fillForward=False)

When you request historical data, the History method uses the fill forward setting of your security subscription. To get historical data with a different fill forward setting, pass a fillForward argument to the History method.

var history = qb.History(qb.Securities.Keys, qb.Time-TimeSpan.FromDays(10), qb.Time, fillForward: true);

history = qb.History(qb.Securities.Keys, qb.Time-timedelta(days=10), qb.Time, fillForward=True)

Extended Market Hours

By default, your security subscriptions only cover regular trading hours. To subscribe to pre and post-market trading hours for a specific asset, enable the extendedMarketHours argument when you create the security subscription.

AddEquity("SPY", extendedMarketHours: true);

self.AddEquity("SPY", extendedMarketHours=True)

You only receive extended market hours data if you create the subscription with minute, second, or tick resolution. If you create the subscription with daily or hourly resolution, the bars only reflect the regular trading hours.

When you request historical data, the History method uses the extended market hours setting of your security subscription. To get historical data with a different extended market hours setting, pass an extendedMarketHours argument to the History method.

var history = qb.History(qb.Securities.Keys, qb.Time-TimeSpan.FromDays(10), qb.Time, extendedMarketHours: false);

history = qb.History(qb.Securities.Keys, qb.Time-timedelta(days=10), qb.Time, extendedMarketHours=False)

Look-Ahead Bias

In the Research Environment, all the historical data is directly available. In backtesting, you can only access the data that is at or before the algorithm time. If you make a history request for the previous 10 days of data in the Research Environment, you get the previous 10 days of data from today's date. If you request the same data in a backtest, you get the previous 10 days of data from the algorithm time.

Consolidate Data

History requests usually return data in one of the standard resolutions . To analyze data on custom time frames like 5-minute bars or 4-hour bars, you need to aggregate it. Consider an example where you make a history call for minute resolution data and want to create 5-minute resolution data.

qb = QuantBook()
symbol = qb.AddEquity("SPY").Symbol
start_date = datetime(2018, 4, 1)
end_date = datetime(2018, 7, 15)
history = qb.History(symbol, start_date, end_date, Resolution.Minute)

var qb = new QuantBook();
var symbol = qb.AddEquity("SPY").Symbol;
var startDate = new DateTime(2018, 4, 1);
var endDate = new DateTime(2018, 7, 15);
var history = qb.History(symbol, startDate, endDate, Resolution.Minute);
foreach (var slice in history)
{
    foreach (var key in slice.Keys)
    {
        Console.WriteLine($"{slice.Time} :: {slice[key].ToString()}");
    }
}

To aggregate the data, use a consolidator or the pandas resample method.

To aggregate the data, use a consolidator .

Consolidators

The following snippet demonstrates how to use a consolidator to aggregate data:

// Set up a consolidator and a RollingWindow to save the data
var consolidator = new TradeBarConsolidator(TimeSpan.FromDays(7));
var window = new RollingWindow<TradeBar>(20);

// Attach a consolidation handler method that saves the consolidated bars in the RollingWindow
consolidator.DataConsolidated += (sender, consolidated) =>
{
    window.Add(consolidated);
};

// Iterate the historical market data and feed each bar into the consolidator
foreach(var bar in history)
{
    consolidator.Update(bar);
}

# Set up a consolidator and a RollingWindow to save the data
consolidator = TradeBarConsolidator(timedelta(7))
window = RollingWindow[TradeBar](20)

# Attach a consolidation handler method that saves the consolidated bars in the RollingWindow   
consolidator.DataConsolidated += lambda _, bar: window.Add(bar)

# Iterate the historical market data and feed each bar into the consolidator
for bar in history.itertuples():
    tradebar = TradeBar(bar.Index[1], bar.Index[0], bar.open, bar.high, bar.low, bar.close, bar.volume)
    consolidator.Update(tradebar)

Resample Method

The resample method converts the frequency of a time series DataFrame into a custom frequency. The method only works on DataFrame objects that have a datetime index. The History method returns a DataFrame with a multi-index. The first index is a Symbol index for each security and the second index is a time index for the timestamps of each row of data. To make the DataFrame compatible with the resample method, call the reset_index method to drop the Symbol index.

# Drop level 0 index (Symbol index) from the DataFrame
history.reset_index(level = 0, drop = True, inplace=True)

The resample method returns a Resampler object, which needs to be downsampled using one of the pandas downsampling computations . For example, you can use the Resampler.ohlc downsampling method to aggregate price data.

When you resample a DataFrame with the ohlc downsampling method, it creates an OHLC row for each column in the DataFrame. To just calculate the OHLC of the close column, select the close column before you resample the DataFrame. A resample offset of 5T corresponds to a 5-minute resample. Other resampling offsets include 2D = 2 days, 5H = 5 hours, and 3S = 3 seconds.

close_prices = history["close"]

offset = "5T" 
close_5min_ohlc = close_prices.resample(offset).ohlc()

Common Errors

If the history request returns an empty DataFrame and you try to slice it, it throws an exception. To avoid issues, check if the DataFrame contains data before slicing it.

df = qb.History(symbol, 10).close    # raises exception if the request is empty

def GetSafeHistoryCloses(symbols):
    if not symbols:
        print(f'No symbols')
        return  False, None
    df = qb.History(symbols, 100, Resolution.Daily)
    if df.empty:
        print(f'Empy history for {symbols}')
        return  False, None
     return True, df.close.unstack(0)

If you run the Research Environment on your local machine and history requests return no data, check if your data directory contains the data you request. To download datasets, see Download .

Datasets > US Equity

Introduction

This page explains how to request, manipulate, and visualize historical US Equity data.

Create Subscriptions

Follow these steps to subscribe to a US Equity security:

1. Load the required assembly files and data types.

#load "../Initialize.csx"
#load "../QuantConnect.csx"
#r "../Microsoft.Data.Analysis.dll"

using QuantConnect;
using QuantConnect.Data;
using QuantConnect.Algorithm;
using QuantConnect.Research;
using QuantConnect.Indicators;
using Microsoft.Data.Analysis;

2. Create a QuantBook .

var qb = new QuantBook();

qb = QuantBook()

3. Call the AddEquity method with a ticker and then save a reference to the US Equity Symbol .

var spy = qb.AddEquity("SPY").Symbol;
var tlt = qb.AddEquity("TLT").Symbol;

spy = qb.AddEquity("SPY").Symbol
tlt = qb.AddEquity("TLT").Symbol

To view the supported assets in the US Equities dataset, see the Data Explorer .

Get Historical Data

You need a subscription before you can request historical data for a security. On the time dimension, you can request an amount of historical data based on a trailing number of bars, a trailing period of time, or a defined period of time. On the security dimension, you can request historical data for a single US Equity, a subset of the US Equities you created subscriptions for in your notebook, or all of the US Equities in your notebook.

Trailing Number of Bars

To get historical data for a number of trailing bars, call the History method with the Symbol object(s) and an integer.

// Slice objects
var singleHistorySlice = qb.History(spy, 10);
var subsetHistorySlice = qb.History(new[] {spy, tlt}, 10);
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(spy, 10);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {spy, tlt}, 10);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, 10);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(spy, 10);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {spy, tlt}, 10);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, 10);

# DataFrame of trade and quote data
single_history_df = qb.History(spy, 10)
subset_history_df = qb.History([spy, tlt], 10)
all_history_df = qb.History(qb.Securities.Keys, 10)

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, spy, 10)
subset_history_trade_bar_df = qb.History(TradeBar, [spy, tlt], 10)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, 10)

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, spy, 10)
subset_history_quote_bar_df = qb.History(QuoteBar, [spy, tlt], 10)
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, 10)

# Slice objects
all_history_slice = qb.History(10)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](spy, 10)
subset_history_trade_bars = qb.History[TradeBar]([spy, tlt], 10)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, 10)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](spy, 10)
subset_history_quote_bars = qb.History[QuoteBar]([spy, tlt], 10)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, 10)

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

Trailing Period of Time

To get historical data for a trailing period of time, call the History method with the Symbol object(s) and a TimeSpan timedelta .

// Slice objects
var singleHistorySlice = qb.History(spy, TimeSpan.FromDays(3));
var subsetHistorySlice = qb.History(new[] {spy, tlt}, TimeSpan.FromDays(3));
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(spy, TimeSpan.FromDays(3));
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {spy, tlt}, TimeSpan.FromDays(3));
var allHistoryTradeBars = qb.History<TradeBar>(TimeSpan.FromDays(3));

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(spy, TimeSpan.FromDays(3), Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {spy, tlt}, TimeSpan.FromDays(3), Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Minute);

// Tick objects
var singleHistoryTicks = qb.History<Tick>(spy, TimeSpan.FromDays(3), Resolution.Tick);
var subsetHistoryTicks = qb.History<Tick>(new[] {spy, tlt}, TimeSpan.FromDays(3), Resolution.Tick);
var allHistoryTicks = qb.History<Tick>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Tick);

# DataFrame of trade and quote data
single_history_df = qb.History(spy, timedelta(days=3))
subset_history_df = qb.History([spy, tlt], timedelta(days=3))
all_history_df = qb.History(qb.Securities.Keys, timedelta(days=3))

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, spy, timedelta(days=3))
subset_history_trade_bar_df = qb.History(TradeBar, [spy, tlt], timedelta(days=3))
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, timedelta(days=3))

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, spy, timedelta(days=3))
subset_history_quote_bar_df = qb.History(QuoteBar, [spy, tlt], timedelta(days=3))
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, timedelta(days=3))

# DataFrame of tick data
single_history_tick_df = qb.History(spy, timedelta(days=3), Resolution.Tick)
subset_history_tick_df = qb.History([spy, tlt], timedelta(days=3), Resolution.Tick)
all_history_tick_df = qb.History(qb.Securities.Keys, timedelta(days=3), Resolution.Tick)

# Slice objects
all_history_slice = qb.History(timedelta(days=3))

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](spy, timedelta(days=3))
subset_history_trade_bars = qb.History[TradeBar]([spy, tlt], timedelta(days=3))
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, timedelta(days=3))

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](spy, timedelta(days=3), Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([spy, tlt], timedelta(days=3), Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, timedelta(days=3), Resolution.Minute)

# Tick objects
single_history_ticks = qb.History[Tick](spy, timedelta(days=3), Resolution.Tick)
subset_history_ticks = qb.History[Tick]([spy, tlt], timedelta(days=3), Resolution.Tick)
all_history_ticks = qb.History[Tick](qb.Securities.Keys, timedelta(days=3), Resolution.Tick)

The preceding calls return the most recent bars or ticks, excluding periods of time when the exchange was closed.

Defined Period of Time

To get historical data for a specific period of time, call the History method with the Symbol object(s), a start DateTime datetime , and an end DateTime datetime . The start and end times you provide are based in the notebook time zone .

var startTime = new DateTime(2021, 1, 1);
var endTime = new DateTime(2021, 2, 1);

// Slice objects
var singleHistorySlice = qb.History(spy, startTime, endTime);
var subsetHistorySlice = qb.History(new[] {spy, tlt}, startTime, endTime);
var allHistorySlice = qb.History(qb.Securities.Keys, startTime, endTime);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(spy, startTime, endTime);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {spy, tlt}, startTime, endTime);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, startTime, endTime);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(spy, startTime, endTime, Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {spy, tlt}, startTime, endTime, Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, startTime, endTime, Resolution.Minute);

// Tick objects
var singleHistoryTicks = qb.History<Tick>(spy, startTime, endTime, Resolution.Tick);
var subsetHistoryTicks = qb.History<Tick>(new[] {spy, tlt}, startTime, endTime, Resolution.Tick);
var allHistoryTicks = qb.History<Tick>(qb.Securities.Keys, startTime, endTime, Resolution.Tick);

start_time = datetime(2021, 1, 1)
end_time = datetime(2021, 2, 1)

# DataFrame of trade and quote data
single_history_df = qb.History(spy, start_time, end_time)
subset_history_df = qb.History([spy, tlt], start_time, end_time)
all_history_df = qb.History(qb.Securities.Keys, start_time, end_time)

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, spy, start_time, end_time)
subset_history_trade_bar_df = qb.History(TradeBar, [spy, tlt], start_time, end_time)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, start_time, end_time)

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, spy, start_time, end_time)
subset_history_quote_bar_df = qb.History(QuoteBar, [spy, tlt], start_time, end_time)
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, start_time, end_time)

# DataFrame of tick data
single_history_tick_df = qb.History(spy, start_time, end_time, Resolution.Tick)
subset_history_tick_df = qb.History([spy, tlt], start_time, end_time, Resolution.Tick)
all_history_tick_df = qb.History(qb.Securities.Keys, start_time, end_time, Resolution.Tick)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](spy, start_time, end_time)
subset_history_trade_bars = qb.History[TradeBar]([spy, tlt], start_time, end_time)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, start_time, end_time)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](spy, start_time, end_time, Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([spy, tlt], start_time, end_time, Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, start_time, end_time, Resolution.Minute)

# Tick objects
single_history_ticks = qb.History[Tick](spy, start_time, end_time, Resolution.Tick)
subset_history_ticks = qb.History[Tick]([spy, tlt], start_time, end_time, Resolution.Tick)
all_history_ticks = qb.History[Tick](qb.Securities.Keys, start_time, end_time, Resolution.Tick)

The preceding calls return the bars or ticks that have a timestamp within the defined period of time.

Resolutions

The following table shows the available resolutions and data formats for Equity subscriptions:

Resolution	TradeBar	QuoteBar	Trade Tick	Quote Tick
Tick
Second
Minute
Hour
Daily

Markets

LEAN groups all of the US Equity exchanges under Market.USA .

Data Normalization

The data normalization mode defines how historical data is adjusted for corporate actions . By default, LEAN adjusts US Equity data for splits and dividends to produce a smooth price curve, but the following data normalization modes are available:

We use the entire split and dividend history to adjust historical prices. This process ensures you get the same adjusted prices, regardless of the QuantBook time.

To set the data normalization mode for a security, pass a dataNormalizationMode argument to the AddEquity method.

var spy = qb.AddEquity("SPY", dataNormalizationMode: DataNormalizationMode.Raw).Symbol;

spy = qb.AddEquity("SPY", dataNormalizationMode=DataNormalizationMode.Raw).Symbol

When you request historical data, the History method uses the data normalization of your security subscription. To get historical data with a different data normalization, pass a dataNormalizationMode argument to the History method.

var history = qb.History(qb.Securities.Keys, qb.Time-TimeSpan.FromDays(10), qb.Time, dataNormalizationMode: DataNormalizationMode.SplitAdjusted);

history = qb.History(qb.Securities.Keys, qb.Time-timedelta(days=10), qb.Time, dataNormalizationMode=DataNormalizationMode.SplitAdjusted)

Wrangle Data

You need some historical data to perform wrangling operations. The process to manipulate the historical data depends on its data type. To display pandas objects, run a cell in a notebook with the pandas object as the last line. To display other data formats, call the print method.

You need some historical data to perform wrangling operations. Use LINQ to wrangle the data and then call the Console.WriteLine method in a Jupyter Notebook to display the data. The process to manipulate the historical data depends on its data type.

DataFrame Objects

If the History method returns a DataFrame , the first level of the DataFrame index is the encoded Equity Symbol and the second level is the EndTime of the data sample. The columns of the DataFrame are the data properties.

To select the historical data of a single Equity, index the loc property of the DataFrame with the Equity Symbol .

all_history_df.loc[spy]  # or all_history_df.loc['SPY']

To select a column of the DataFrame , index it with the column name.

all_history_df.loc[spy]['close']

If you request historical data for multiple Equities, you can transform the DataFrame so that it's a time series of close values for all of the Equities. To transform the DataFrame , select the column you want to display for each Equity and then call the unstack method.

all_history_df['close'].unstack(level=0)

The DataFrame is transformed so that the column indices are the Symbol of each Equity and each row contains the close value.

If you prefer to display the ticker of each Symbol instead of the string representation of the SecurityIdentifier , follow these steps:

1. Create a dictionary where the keys are the string representations of each SecurityIdentifier and the values are the ticker.

tickers_by_id = {str(x.ID): x.Value for x in qb.Securities.Keys}

2. Get the values of the symbol level of the DataFrame index and create a list of tickers.

tickers = set([tickers_by_id[x] for x in all_history_df.index.get_level_values('symbol')])

3. Set the values of the symbol level of the DataFrame index to the list of tickers.

all_history_df.index.set_levels(tickers, 'symbol', inplace=True)

The new DataFrame is keyed by the ticker.

all_history_df.loc[spy.Value]  # or all_history_df.loc["SPY"]  

After the index renaming, the unstacked DataFrame has the following format:

The historical data methods don't return DataFrame objects, but you can create one for efficient vectorized data wrangling.

using Microsoft.Data.Analysis; 

var columns = new DataFrameColumn[] {
    new PrimitiveDataFrameColumn("Time", history.Select(x => x[spy].EndTime)),
    new DecimalDataFrameColumn("SPY Open", history.Select(x => x[spy].Open)),
    new DecimalDataFrameColumn("SPY High", history.Select(x => x[spy].High)),
    new DecimalDataFrameColumn("SPY Low", history.Select(x => x[spy].Low)),
    new DecimalDataFrameColumn("SPY Close", history.Select(x => x[spy].Close))
};
var df = new DataFrame(columns);
df

To select a particular column of the DataFrame, index it with the column name.

df["SPY close"]

Slice Objects

If the History method returns Slice objects, iterate through the Slice objects to get each one. The Slice objects may not have data for all of your Equity subscriptions. To avoid issues, check if the Slice contains data for your Equity before you index it with the Equity Symbol .

foreach (var slice in allHistorySlice) {
    if (slice.Bars.ContainsKey(spy))
    {
        var tradeBar = slice.Bars[spy];
    }
    if (slice.QuoteBars.ContainsKey(spy))
    {
        var quoteBar = slice.QuoteBars[spy];
    }
}

for slice in all_history_slice:
        if slice.Bars.ContainsKey(spy):
        trade_bar = slice.Bars[spy]
    if slice.QuoteBars.ContainsKey(spy):
        quote_bar = slice.QuoteBars[spy]

You can also iterate through each TradeBar and QuoteBar in the Slice .

foreach (var slice in allHistorySlice)
{
    foreach (var kvp in slice.Bars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
    foreach (var kvp in slice.QuoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for slice in all_history_slice:
    for kvp in slice.Bars:
        symbol = kvp.Key
        trade_bar = kvp.Value
    for kvp in slice.QuoteBars:
        symbol = kvp.Key
        quote_bar = kvp.Value

You can also use LINQ to select each TradeBar in the Slice for a given Symbol .

var tradeBars = allHistorySlice.Where(slice => slice.Bars.ContainsKey(spy)).Select(slice => slice.Bars[spy]);

TradeBar Objects

If the History method returns TradeBar objects, iterate through the TradeBar objects to get each one.

foreach (var tradeBar in singleHistoryTradeBars)
{
    Console.WriteLine(tradeBar);
}

for trade_bar in single_history_trade_bars:
    print(trade_bar)

If the History method returns TradeBars , iterate through the TradeBars to get the TradeBar of each Equity. The TradeBars may not have data for all of your Equity subscriptions. To avoid issues, check if the TradeBars object contains data for your security before you index it with the Equity Symbol .

foreach (var tradeBars in allHistoryTradeBars)
{
    if (tradeBars.ContainsKey(spy))
    {
        var tradeBar = tradeBars[spy];
    }
}

for trade_bars in all_history_trade_bars:
    if trade_bars.ContainsKey(spy):
        trade_bar = trade_bars[spy]

You can also iterate through each of the TradeBars .

foreach (var tradeBars in allHistoryTradeBars)
{
    foreach (var kvp in tradeBars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
}

for trade_bars in all_history_trade_bars:
    for kvp in trade_bars:
        symbol = kvp.Key
        trade_bar = kvp.Value

QuoteBar Objects

If the History method returns QuoteBar objects, iterate through the QuoteBar objects to get each one.

foreach (var quoteBar in singleHistoryQuoteBars)
{
    Console.WriteLine(quoteBar);
}

for quote_bar in single_history_quote_bars:
    print(quote_bar)

If the History method returns QuoteBars , iterate through the QuoteBars to get the QuoteBar of each Equity. The QuoteBars may not have data for all of your Equity subscriptions. To avoid issues, check if the QuoteBars object contains data for your security before you index it with the Equity Symbol .

foreach (var quoteBars in allHistoryQuoteBars)
{
    if (quoteBars.ContainsKey(spy))
    {
        var quoteBar = quoteBars[spy];
    }
}

for quote_bars in all_history_quote_bars:
    if quote_bars.ContainsKey(spy):
        quote_bar = quote_bars[spy]

You can also iterate through each of the QuoteBars .

foreach (var quoteBars in allHistoryQuoteBars)
{
    foreach (var kvp in quoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for quote_bars in all_history_quote_bars:
    for kvp in quote_bars:
        symbol = kvp.Key
        quote_bar = kvp.Value

Tick Objects

If the History method returns Tick objects, iterate through the Tick objects to get each one.

foreach (var tick in singleHistoryTicks)
{
    Console.WriteLine(tick);
}

for tick in single_history_ticks:
    print(tick)

If the History method returns Ticks , iterate through the Ticks to get the Tick of each Equity. The Ticks may not have data for all of your Equity subscriptions. To avoid issues, check if the Ticks object contains data for your security before you index it with the Equity Symbol .

foreach (var ticks in allHistoryTicks)
{
    if (ticks.ContainsKey(spy))
    {
        var tick = ticks[spy];
    }
}

for ticks in all_history_ticks:
    if ticks.ContainsKey(spy):
        ticks = ticks[spy]

You can also iterate through each of the Ticks .

foreach (var ticks in allHistoryTicks)
{
    foreach (var kvp in ticks)
    {
        var symbol = kvp.Key;
        var tick = kvp.Value;
    }
}

for ticks in all_history_ticks:
    for kvp in ticks:
        symbol = kvp.Key
        tick = kvp.Value

Plot Data

You need some historical Equity data to produce plots. You can use many of the supported plotting libraries Plot.NET package to visualize data in various formats. For example, you can plot candlestick and line charts.

Candlestick Chart

Follow these steps to plot candlestick charts:

1. Get some historical data.

history = qb.History(spy, datetime(2021, 11, 23), datetime(2021, 12, 8), Resolution.Daily).loc[spy]

var history = qb.History<TradeBar>(spy, new DateTime(2021, 11, 23), new DateTime(2021, 12, 8), Resolution.Daily);

2. Import the plotly Plotly.NET library.

import plotly.graph_objects as go

#r "../Plotly.NET.dll"
using Plotly.NET;
using Plotly.NET.LayoutObjects;

3. Create a Candlestick chart.
   

candlestick = go.Candlestick(x=history.index,
                             open=history['open'],
                             high=history['high'],
                             low=history['low'],
                             close=history['close'])

var chart = Chart2D.Chart.Candlestick<decimal, decimal, decimal, decimal, DateTime, string>(
    history.Select(x => x.Open),
    history.Select(x => x.High),
    history.Select(x => x.Low),
    history.Select(x => x.Close),
    history.Select(x => x.EndTime)
);

4. Create a Layout .
   

layout = go.Layout(title=go.layout.Title(text='SPY OHLC'),
                   xaxis_title='Date',
                   yaxis_title='Price',
                   xaxis_rangeslider_visible=False)

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init("SPY Price");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

5. Create the Figure .
   
6. Assign the Layout to the chart.
   

fig = go.Figure(data=[candlestick], layout=layout)

chart.WithLayout(layout);

7. Show the plot.
   

fig.show()

HTML(GenericChart.toChartHTML(chart))

Candlestick charts display the open, high, low, and close prices of the security.

Line Chart

Follow these steps to plot line charts using built-in methods Plotly.NET package :

1. Get some historical data.

history = qb.History([spy, tlt], datetime(2021, 11, 23), datetime(2021, 12, 8), Resolution.Daily)

var history = qb.History<TradeBar>(new [] {spy, tlt}, new DateTime(2021, 11, 23), new DateTime(2021, 12, 8), Resolution.Daily);

2. Select the data to plot.

volume = history['volume'].unstack(level=0)

var spy = history.Select(x => x["SPY"]);

3. Call the plot method on the pandas object.
4. Create a Line chart.

volume.plot(title="Volume", figsize=(15, 10))

var chart = Chart2D.Chart.Line<DateTime, decimal, string>(
    spy.Select(x => x.EndTime),
    spy.Select(x => x.Volume)
);

5. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Volume");
Title title = Title.init("SPY Volume");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

6. Assign the Layout to the chart.
   

chart.WithLayout(layout);

7. Show the plot.

plt.show()

HTML(GenericChart.toChartHTML(chart))

Line charts display the value of the property you selected in a time series.

Common Errors

Some factor files have INF split values, which indicate that the stock has so many splits that prices can't be calculated with correct numerical precision. To allow history requests with these symbols, we need to move the starting date forward when reading the data. If there are numerical precision errors in the factor files for a security in your history request, LEAN throws the following error:

Datasets > Equity Fundamental Data

Introduction

This page explains how to request, manipulate, and visualize historical Equity Fundamental data. Corporate fundamental data is available through the US Fundamental Data from Morningstar .

Create Subscriptions

Follow these steps to subscribe to an Equity security:

1. Load the required assembly files and data types.

#load "../Initialize.csx"
#load "../QuantConnect.csx"
#r "../Microsoft.Data.Analysis.dll"

using QuantConnect;
using QuantConnect.Data;
using QuantConnect.Algorithm;
using QuantConnect.Research;
using QuantConnect.Indicators;
using Microsoft.Data.Analysis;

2. Create a QuantBook .

var qb = new QuantBook();

qb = QuantBook()

3. Call the AddEquity method with a ticker and then save a reference to the Equity Symbol .

var symbols = new [] 
    {
        "AAL",  // American Airlines Group, Inc.
        "ALGT", // Allegiant Travel Company
        "ALK",  // Alaska Air Group, Inc.
        "DAL",  // Delta Air Lines, Inc.
        "LUV",  // Southwest Airlines Company
        "SKYW", // SkyWest, Inc.
        "UAL"   // United Air Lines
    }
    .Select(ticker => qb.AddEquity(ticker).Symbol);

symbols = [qb.AddEquity(ticker).Symbol
    for ticker in [
        "AAL",   # American Airlines Group, Inc.
        "ALGT",  # Allegiant Travel Company
        "ALK",   # Alaska Air Group, Inc.
        "DAL",   # Delta Air Lines, Inc.
        "LUV",   # Southwest Airlines Company
        "SKYW",  # SkyWest, Inc.
        "UAL"    # United Air Lines
    ]]

To view the supported assets in the US Equities dataset, see the Data Explorer .

Get Historical Data

You need a subscription before you can request historical fundamental data for a US Equity.

To get historical data, call the GetFundamental method with a list of Symbol objects, a fundamental data field name, a start DateTime datetime , and an end DateTime datetime . The start and end times you provide are based in the notebook time zone . To view the possible fundamental data field names, see the FineFundamental attributes in Data Point Attributes . For example, to get data for airline companies over 2014, run:

var startTime = new DateTime(2014, 1, 1);
var endTime = new DateTime(2015, 1, 1);
var history = qb.GetFundamental(symbols, "ValuationRatios.PERatio", startTime, endTime);

start_time = datetime(2014, 1, 1)
end_time = datetime(2015, 1, 1)
history = qb.GetFundamental(symbols, "ValuationRatios.PERatio", start_time, end_time)

The preceding method returns the fundamental data field values that are timestamped within the defined period of time.

Wrangle Data

You need some historical data to perform wrangling operations. To display pandas objects, run a cell in a notebook with the pandas object as the last line. To display other data formats, call the print method.

You need some historical data to perform wrangling operations. Use LINQ to wrangle the data and then call the Console.WriteLine method in a Jupyter Notebook to display the data.

The DataFrame index is the EndTime of the data sample. The columns of the DataFrame are the Equity Symbol objects.

To get the fundamental data points for each Equity, iterate through the history request result.

To select the historical data of a single Equity, index the DataFrame with the Equity Symbol . Each history slice may not have data for all of your Equity subscriptions. To avoid issues, check if it contains data for your Equity before you index it with the Equity Symbol .

foreach (var slice in history)
{
    foreach (var symbol in symbols)
    {
        if (slice.ContainsKey(symbol))
        {
            var peRatio = slice[symbol];
        }
    }
}

history[symbols[1]]

You can also iterate through each data point in the slice.

foreach (var slice in history)
{
    foreach (var kvp in slice)
    {
        var symbol = kvp.Key;
        var peRatio = kvp.Value;
    }
}

You can also use LINQ to select the historical data points.

var symbol = symbols.Last();
var values = history.Select(slice => slice[symbol]);

Plot Data

You need some historical Equity fundamental data to produce plots. You can use many of the supported plotting libraries Plot.NET package to visualize data in various formats. For example, you can plot line charts.

Follow these steps to plot line charts using built-in methods Plotly.NET package :

1. Call the plot method on the history DataFrame .

history.plot(title='PE Ratio Over Time', figsize=(15, 8))

2. Create Line charts.

var chart1 = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => (DateTime)x.Time),
    history.Select(x => (decimal)x[aapl]),
    Name: "AAPL"
);
var chart2 = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => (DateTime)x.Time),
    history.Select(x => (decimal)x[goog]),
    Name: "GOOG"
);

3. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "PE Ratio");
Title title = Title.init("AAPL & GOOG PE Ratio");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

4. Combine the charts and assign the Layout to the chart.
   

var chart = Plotly.NET.Chart.Combine(new []{chart1, chart2});
chart.WithLayout(layout);

5. Show the plot.

plt.show()

HTML(GenericChart.toChartHTML(chart))

Line charts display the value of the property you selected in a time series.

Datasets > Equity Options

Introduction

This page explains how to request, manipulate, and visualize historical Equity Options data.

Create Subscriptions

Follow these steps to subscribe to an Equity Option security:

1. Load the required assembly files and data types.

#load "../Initialize.csx"
#load "../QuantConnect.csx"
#r "../Microsoft.Data.Analysis.dll"

using QuantConnect;
using QuantConnect.Data;
using QuantConnect.Data.Market;
using QuantConnect.Algorithm;
using QuantConnect.Securities;
using QuantConnect.Securities.Option;
using QuantConnect.Research;
using Microsoft.Data.Analysis;

2. Create a QuantBook .

var qb = new QuantBook();

qb = QuantBook()

3. Subscribe to the underlying Equity with raw data normalization and save a reference to the Equity Symbol .

var equitySymbol = qb.AddEquity("SPY", dataNormalizationMode: DataNormalizationMode.Raw).Symbol;

equity_symbol = qb.AddEquity("SPY", dataNormalizationMode=DataNormalizationMode.Raw).Symbol

To view the supported underlying assets in the US Equity Options dataset, see the Data Explorer .

4. Call the AddOption method with the underlying Equity Symbol .

var option = qb.AddOption(equitySymbol);

option = qb.AddOption(equity_symbol)

5. (Optional) Set a contract filter .

option.SetFilter(-1, 1, 0, 90);

option.SetFilter(-1, 1, 0, 90)

The filter determines which contracts the GetOptionHistory method returns. If you don't set a filter, the default filter selects the contracts that have the following characteristics:

• Standard type (exclude weeklys)
• Within 1 strike price of the underlying asset price
• Expire within 31 days

option.PriceModel = OptionPriceModels.BjerksundStensland();

option.PriceModel = OptionPriceModels.BjerksundStensland()

If you want historical data on individual contracts and their OpenInterest , follow these steps to subscribe to the individual Equity Option contracts:

1. Call the GetOptionsContractList method with the underlying Equity Symbol and a datetime DateTime .

var startDate = new DateTime(2021, 12, 31);
var contractSymbols = qb.OptionChainProvider.GetOptionContractList(equitySymbol, startDate);

start_date = datetime(2021, 12, 31)
contract_symbols = qb.OptionChainProvider.GetOptionContractList(equity_symbol, start_date)

This method returns a list of Symbol objects that reference the Option contracts that were trading at the given time. If you set a contract filter with SetFilter , it doesn't affect the results of GetOptionsContractList .

2. Select the Symbol of the OptionContract object(s) for which you want to get historical data.

To filter and select contracts, you can use the following properties of each Symbol object:

Property	Description
ID.Date	The expiration date of the contract.
ID.StrikePrice	The strike price of the contract.
ID.OptionRight	The contract type. The OptionRight enumeration has the following members:
ID.OptionStyle	The contract style. The OptionStyle enumeration has the following members:

var contractSymbol = contractSymbols.Where(s => 
    s.ID.OptionRight == OptionRight.Call &&
    s.ID.StrikePrice == 477 &&
    s.ID.Date == new DateTime(2022, 1, 21)).First();

contract_symbol = [s for s in contract_symbols 
    if s.ID.OptionRight == OptionRight.Call 
        and s.ID.StrikePrice == 477 
        and s.ID.Date == datetime(2022, 1, 21)][0]

3. Call the AddOptionContract method with an OptionContract Symbol and disable fill-forward.

var optionContract = qb.AddOptionContract(contractSymbol, fillForward: false);

option_contract = qb.AddOptionContract(contract_symbol, fillForward = False)

Disable fill-forward because there are only a few OpenInterest data points per day.

4. (Optional) Set the price model .

optionContract.PriceModel = OptionPriceModels.BjerksundStensland();

option_contract.PriceModel = OptionPriceModels.BjerksundStensland()

Get Historical Data

You need a subscription before you can request historical data for Equity Option contracts. On the time dimension, you can request an amount of historical data based on a trailing number of bars, a trailing period of time, or a defined period of time. On the contract dimension, you can request historical data for a single contract, a subset of the contracts you created subscriptions for in your notebook, or all of the contracts in your notebook.

Before you request historical data, call the SetStartDate method with a datetime DateTime to reduce the risk of look-ahead bias .

qb.SetStartDate(startDate);

qb.SetStartDate(start_date)

If you call the SetStartDate method, the date that you pass to the method is the latest date for which your history requests will return data.

Trailing Number of Bars

To get historical data for a number of trailing bars, call the History method with the contract Symbol object(s) and an integer.

// Slice objects
var singleHistorySlice = qb.History(contractSymbol, 10);
var subsetHistorySlice = qb.History(new[] {contractSymbol}, 10);
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(contractSymbol, 10);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {contractSymbol}, 10);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, 10);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(contractSymbol, 10);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {contractSymbol}, 10);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, 10);

// OpenInterest objects
var singleHistoryOpenInterest = qb.History<OpenInterest>(contractSymbol, 400);
var subsetHistoryOpenInterest = qb.History<OpenInterest>(new[] {contractSymbol}, 400);
var allHistoryOpenInterest = qb.History<OpenInterest>(qb.Securities.Keys, 400);

# DataFrame of trade and quote data
single_history_df = qb.History(contract_symbol, 10)
subset_history_df = qb.History([contract_symbol], 10)
all_history_df = qb.History(qb.Securities.Keys, 10)

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, contract_symbol, 10)
subset_history_trade_bar_df = qb.History(TradeBar, [contract_symbol], 10)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, 10)

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, contract_symbol, 10)
subset_history_quote_bar_df = qb.History(QuoteBar, [contract_symbol], 10)
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, 10)

# DataFrame of open interest data
single_history_open_interest_df = qb.History(OpenInterest, contract_symbol, 400)
subset_history_open_interest_df = qb.History(OpenInterest, [contract_symbol], 400)
all_history_open_interest_df = qb.History(OpenInterest, qb.Securities.Keys, 400)

# Slice objects
all_history_slice = qb.History(10)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](contract_symbol, 10)
subset_history_trade_bars = qb.History[TradeBar]([contract_symbol], 10)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, 10)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](contract_symbol, 10)
subset_history_quote_bars = qb.History[QuoteBar]([contract_symbol], 10)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, 10)

# OpenInterest objects
single_history_open_interest = qb.History[OpenInterest](contract_symbol, 400)
subset_history_open_interest = qb.History[OpenInterest]([contract_symbol], 400)
all_history_open_interest = qb.History[OpenInterest](qb.Securities.Keys, 400)

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

Trailing Period of Time

To get historical data for a trailing period of time, call the History method with the contract Symbol object(s) and a TimeSpan timedelta .

// Slice objects
var singleHistorySlice = qb.History(contractSymbol, TimeSpan.FromDays(3));
var subsetHistorySlice = qb.History(new[] {contractSymbol}, TimeSpan.FromDays(3));
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(contractSymbol, TimeSpan.FromDays(3));
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {contractSymbol}, TimeSpan.FromDays(3));
var allHistoryTradeBars = qb.History<TradeBar>(TimeSpan.FromDays(3));

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(contractSymbol, TimeSpan.FromDays(3), Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {contractSymbol}, TimeSpan.FromDays(3), Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Minute);


// OpenInterest objects
var singleHistoryOpenInterest = qb.History<OpenInterest>(contractSymbol, TimeSpan.FromDays(2));
var subsetHistoryOpenInterest = qb.History<OpenInterest>(new[] {contractSymbol}, TimeSpan.FromDays(2));
var allHistoryOpenInterest = qb.History<OpenInterest>(qb.Securities.Keys, TimeSpan.FromDays(2));

# DataFrame of trade and quote data
single_history_df = qb.History(contract_symbol, timedelta(days=3))
subset_history_df = qb.History([contract_symbol], timedelta(days=3))
all_history_df = qb.History(qb.Securities.Keys, timedelta(days=3))

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, contract_symbol, timedelta(days=3))
subset_history_trade_bar_df = qb.History(TradeBar, [contract_symbol], timedelta(days=3))
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, timedelta(days=3))

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, contract_symbol, timedelta(days=3))
subset_history_quote_bar_df = qb.History(QuoteBar, [contract_symbol], timedelta(days=3))
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, timedelta(days=3))

# DataFrame of open interest data
single_history_open_interest_df = qb.History(OpenInterest, contract_symbol, timedelta(days=3))
subset_history_open_interest_df = qb.History(OpenInterest, [contract_symbol], timedelta(days=3))
all_history_open_interest_df = qb.History(OpenInterest, qb.Securities.Keys, timedelta(days=3))

# Slice objects
all_history_slice = qb.History(timedelta(days=3))

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](contract_symbol, timedelta(days=3))
subset_history_trade_bars = qb.History[TradeBar]([contract_symbol], timedelta(days=3))
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, timedelta(days=3))

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](contract_symbol, timedelta(days=3), Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([contract_symbol], timedelta(days=3), Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, timedelta(days=3), Resolution.Minute) 


# OpenInterest objects
single_history_open_interest = qb.History[OpenInterest](contract_symbol, timedelta(days=2))
subset_history_open_interest = qb.History[OpenInterest]([contract_symbol], timedelta(days=2))
all_history_open_interest = qb.History[OpenInterest](qb.Securities.Keys, timedelta(days=2))

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

Defined Period of Time

To get historical data for individual Equity Option contracts during a specific period of time, call the History method with the Equity Option contract Symbol object(s), a start DateTime datetime , and an end DateTime datetime . The start and end times you provide are based in the notebook time zone .

var startTime = new DateTime(2021, 12, 1);
var endTime = new DateTime(2021, 12, 31);

// Slice objects
var singleHistorySlice = qb.History(contractSymbol, startTime, endTime);
var subsetHistorySlice = qb.History(new[] {contractSymbol}, startTime, endTime);
var allHistorySlice = qb.History(startTime, endTime);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(contractSymbol, startTime, endTime);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {contractSymbol}, startTime, endTime);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, startTime, endTime);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(contractSymbol, startTime, endTime, Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {contractSymbol}, startTime, endTime, Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, startTime, endTime, Resolution.Minute);


// OpenInterest objects
var singleHistoryOpenInterest = qb.History<OpenInterest>(contractSymbol, startTime, endTime);
var subsetHistoryOpenInterest = qb.History<OpenInterest>(new[] {contractSymbol}, startTime, endTime);
var allHistoryOpenInterest = qb.History<OpenInterest>(qb.Securities.Keys, startTime, endTime);

start_time = datetime(2021, 12, 1)
end_time = datetime(2021, 12, 31)

# DataFrame of trade and quote data
single_history_df = qb.History(contract_symbol, start_time, end_time)
subset_history_df = qb.History([contract_symbol], start_time, end_time)
all_history_df = qb.History(qb.Securities.Keys, start_time, end_time)

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, contract_symbol, start_time, end_time)
subset_history_trade_bar_df = qb.History(TradeBar, [contract_symbol], start_time, end_time)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, start_time, end_time)

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, contract_symbol, start_time, end_time)
subset_history_quote_bar_df = qb.History(QuoteBar, [contract_symbol], start_time, end_time)
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, start_time, end_time)

# DataFrame of open interest data
single_history_open_interest_df = qb.History(OpenInterest, contract_symbol, start_time, end_time)
subset_history_open_interest_df = qb.History(OpenInterest, [contract_symbol], start_time, end_time)
all_history_trade_open_interest_df = qb.History(OpenInterest, qb.Securities.Keys, start_time, end_time)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](contract_symbol, start_time, end_time)
subset_history_trade_bars = qb.History[TradeBar]([contract_symbol], start_time, end_time)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, start_time, end_time)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](contract_symbol, start_time, end_time, Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([contract_symbol], start_time, end_time, Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, start_time, end_time, Resolution.Minute)


# OpenInterest objects
single_history_open_interest = qb.History[OpenInterest](contract_symbol, start_time, end_time)
subset_history_open_interest = qb.History[OpenInterest]([contract_symbol], start_time, end_time)
all_history_open_interest = qb.History[OpenInterest](qb.Securities.Keys, start_time, end_time)

To get historical data for all of the Equity Option contracts that pass your filter during a specific period of time, call the GetOptionHistory method with the underlying Equity Symbol object, a start DateTime datetime , and an end DateTime datetime .

option_history = qb.GetOptionHistory(equity_symbol, end_time-timedelta(days=2), end_time, Resolution.Minute, fillForward=False, extendedMarketHours=False)

var optionHistory = qb.GetOptionHistory(equitySymbol, endTime-TimeSpan.FromDays(2), endTime, Resolution.Minute, fillForward: False, extendedMarketHours: False);

The preceding calls return data that have a timestamp within the defined period of time.

Resolutions

The following table shows the available resolutions and data formats for Equity Option contract subscriptions:

Resolution	TradeBar	QuoteBar	Trade Tick	Quote Tick
Tick
Second
Minute
Hour
Daily

Markets

LEAN groups all of the US Equity Option exchanges under Market.USA , so you don't need to pass a Market to the AddOption or AddOptionContract methods.

Wrangle Data

You need some historical data to perform wrangling operations. The process to manipulate the historical data depends on its data type. To display pandas objects, run a cell in a notebook with the pandas object as the last line. To display other data formats, call the print method.

You need some historical data to perform wrangling operations. Use LINQ to wrangle the data and then call the Console.WriteLine method in a Jupyter Notebook to display the data. The process to manipulate the historical data depends on its data type.

DataFrame Objects

If your history request returns a DataFrame , the DataFrame has the following index levels:

1. Contract expiry
2. Contract strike price
3. Contract type (call or put)
4. Encoded contract Symbol
5. The EndTime of the data sample

The columns of the DataFrame are the data properties. Depending on how you request data, the DataFrame may contain data for the underlying security, which causes some of the index levels to be an empty string for the corresponding rows.

To select the rows of the contract(s) that expire at a specific time, index the loc property of the DataFrame with the expiry time.

all_history_df.loc[datetime(2022, 1, 21)]

If you remove the first three index levels, you can index the DataFrame with just the contract Symbol , similiar to how you would with non-derivative asset classes. To remove the first three index levels, call the droplevel method.

all_history_df.index = all_history_df.index.droplevel([0,1,2])

To select the historical data of a single Equity Options contract, index the loc property of the DataFrame with the contract Symbol .

all_history_df.loc[contract_symbol]

To select a column of the DataFrame , index it with the column name.

all_history_df.loc[contract_symbol]['close']

If you request historical data for multiple Equity Option contracts, you can transform the DataFrame so that it's a time series of close values for all of the Equity Option contracts. To transform the DataFrame , select the column you want to display for each Equity Option contract and then call the unstack method.

all_history_df['close'].unstack(level=0)

The DataFrame is transformed so that the column indices are the Symbol of each security and each row contains the close value.

The historical data methods don't return DataFrame objects, but you can create one for efficient vectorized data wrangling.

using Microsoft.Data.Analysis; 

var columns = new DataFrameColumn[] {
    new PrimitiveDataFrameColumn("Time", history.Select(x => x[contractSymbol].EndTime)),
    new DecimalDataFrameColumn(" Open", history.Select(x => x[contractSymbol].Open)),
    new DecimalDataFrameColumn(" High", history.Select(x => x[contractSymbol].High)),
    new DecimalDataFrameColumn(" Low", history.Select(x => x[contractSymbol].Low)),
    new DecimalDataFrameColumn(" Close", history.Select(x => x[contractSymbol].Close))
};
var df = new DataFrame(columns);
df

To select a particular column of the DataFrame, index it with the column name.

df[" close"]

Slice Objects

If the History method returns Slice objects, iterate through the Slice objects to get each one. The Slice objects may not have data for all of your Equity Options subscriptions. To avoid issues, check if the Slice contains data for your Equity Option contract before you index it with the Equity Options Symbol .

foreach (var slice in allHistorySlice) {
    if (slice.Bars.ContainsKey(contractSymbol))
    {
        var tradeBar = slice.Bars[contractSymbol];
    }
    if (slice.QuoteBars.ContainsKey(contractSymbol))
    {
        var quoteBar = slice.QuoteBars[contractSymbol];
    }
}

for slice in all_history_slice:
        if slice.Bars.ContainsKey(contract_symbol):
        trade_bar = slice.Bars[contract_symbol]
    if slice.QuoteBars.ContainsKey(contract_symbol):
        quote_bar = slice.QuoteBars[contract_symbol]

You can also iterate through each TradeBar and QuoteBar in the Slice .

foreach (var slice in allHistorySlice)
{
    foreach (var kvp in slice.Bars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
    foreach (var kvp in slice.QuoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for slice in all_history_slice:
    for kvp in slice.Bars:
        symbol = kvp.Key
        trade_bar = kvp.Value
    for kvp in slice.QuoteBars:
        symbol = kvp.Key
        quote_bar = kvp.Value

You can also use LINQ to select each TradeBar in the Slice for a given Symbol .

var tradeBars = allHistorySlice.Where(slice => slice.Bars.ContainsKey(contractSymbol)).Select(slice => slice.Bars[contractSymbol]);

TradeBar Objects

If the History method returns TradeBar objects, iterate through the TradeBar objects to get each one.

foreach (var tradeBar in singleHistoryTradeBars)
{
    Console.WriteLine(tradeBar);
}

for trade_bar in single_history_trade_bars:
    print(trade_bar)

If the History method returns TradeBars , iterate through the TradeBars to get the TradeBar of each Equity Option contract. The TradeBars may not have data for all of your Equity Options subscriptions. To avoid issues, check if the TradeBars object contains data for your security before you index it with the Equity Options Symbol .

foreach (var tradeBars in allHistoryTradeBars)
{
    if (tradeBars.ContainsKey(contractSymbol))
    {
        var tradeBar = tradeBars[contractSymbol];
    }
}

for trade_bars in all_history_trade_bars:
    if trade_bars.ContainsKey(contract_symbol):
        trade_bar = trade_bars[contract_symbol]

You can also iterate through each of the TradeBars .

foreach (var tradeBars in allHistoryTradeBars)
{
    foreach (var kvp in tradeBars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
}

for trade_bars in all_history_trade_bars:
    for kvp in trade_bars:
        symbol = kvp.Key
        trade_bar = kvp.Value

QuoteBar Objects

If the History method returns QuoteBar objects, iterate through the QuoteBar objects to get each one.

foreach (var quoteBar in singleHistoryQuoteBars)
{
    Console.WriteLine(quoteBar);
}

for quote_bar in single_history_quote_bars:
    print(quote_bar)

If the History method returns QuoteBars , iterate through the QuoteBars to get the QuoteBar of each Equity Option contract. The QuoteBars may not have data for all of your Equity Options subscriptions. To avoid issues, check if the QuoteBars object contains data for your security before you index it with the Equity Options Symbol .

foreach (var quoteBars in allHistoryQuoteBars)
{
    if (quoteBars.ContainsKey(contractSymbol))
    {
        var quoteBar = quoteBars[contractSymbol];
    }
}

for quote_bars in all_history_quote_bars:
    if quote_bars.ContainsKey(contract_symbol):
        quote_bar = quote_bars[contract_symbol]

You can also iterate through each of the QuoteBars .

foreach (var quoteBars in allHistoryQuoteBars)
{
    foreach (var kvp in quoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for quote_bars in all_history_quote_bars:
    for kvp in quote_bars:
        symbol = kvp.Key
        quote_bar = kvp.Value

OpenInterest Objects

If the History method returns OpenInterest objects, iterate through the OpenInterest objects to get each one.

foreach (var openInterest in singleHistoryOpenInterest)
{
    Console.WriteLine(openInterest);
}

for open_interest in single_history_open_interest:
    print(open_interest)

If the History method returns a dictionary of OpenInterest objects, iterate through the dictionary to get the OpenInterest of each Equity Option contract. The dictionary of OpenInterest objects may not have data for all of your Equity Options contract subscriptions. To avoid issues, check if the dictionary contains data for your contract before you index it with the Equity Options contract Symbol .

foreach (var openInterestDict in allHistoryOpenInterest)
{
    if (openInterestDict.ContainsKey(contractSymbol))
    {
        var openInterest = openInterestDict[contractSymbol];
    }
}

for open_interest_dict in all_history_open_interest:
    if open_interest_dict.ContainsKey(contract_symbol):
        open_interest = open_interest_dict[contract_symbol]

You can also iterate through each of the OpenInterest dictionaries.

foreach (var openInterestDict in allHistoryOpenInterest)
{
    foreach (var kvp in openInterestDict)
    {
        var symbol = kvp.Key;
        var openInterest = kvp.Value;
    }
}

for open_interest_dict in all_history_open_interest:
    for kvp in open_interest_dict:
        symbol = kvp.Key
        open_interest = kvp.Value

OptionHistory Objects

The GetOptionHistory method returns an OptionHistory object. To get each slice in the OptionHistory object, iterate through it.

foreach (var slice in optionHistory)
{
    foreach (var kvp in slice.OptionChains)
    {
        var canonicalSymbol = kvp.Key;
        var chain = kvp.Value;
        foreach (var contract in chain)
        {
            
        }
    }
}

for slice in option_history:
    for canonical_symbol, chain in slice.OptionChains.items(): 
        for contract in chain:
            pass

To convert the OptionHistory object to a DataFrame that contains the trade and quote information of each contract and the underlying, call the GetAllData method.

option_history.GetAllData()

To get the expiration dates of all the contracts in an OptionHistory object, call the GetExpiryDates method.

option_history.GetExpiryDates()

To get the strike prices of all the contracts in an OptionHistory object, call the GetStrikes method.

option_history.GetStrikes()

Plot Data

You need some historical Equity Options data to produce plots. You can use many of the supported plotting libraries Plot.NET package to visualize data in various formats. For example, you can plot candlestick and line charts.

Candlestick Chart

Follow these steps to plot candlestick charts:

1. Get some historical data.

history = qb.History(contract_symbol, datetime(2021, 12, 30), datetime(2021, 12, 31))

var history = qb.History<TradeBar>(contractSymbol, new DateTime(2021, 12, 30), new DateTime(2021, 12, 31));

2. Drop the first four index levels of the DataFrame that returns.

history.index = history.index.droplevel([0,1,2,3])

3. Import the plotly Plotly.NET library.

import plotly.graph_objects as go

#r "../Plotly.NET.dll"
using Plotly.NET;
using Plotly.NET.LayoutObjects;

4. Create a Candlestick .

candlestick = go.Candlestick(x=history.index,
                             open=history['open'],
                             high=history['high'],
                             low=history['low'],
                             close=history['close'])

var chart = Chart2D.Chart.Candlestick<decimal, decimal, decimal, decimal, DateTime, string>(
    history.Select(x => x.Open),
    history.Select(x => x.High),
    history.Select(x => x.Low),
    history.Select(x => x.Close),
    history.Select(x => x.EndTime)
);

5. Create a Layout .

layout = go.Layout(title=go.layout.Title(text=f'{symbol.Value} OHLC'),
                   xaxis_title='Date',
                   yaxis_title='Price',
                   xaxis_rangeslider_visible=False)

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{contractSymbol} Price");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

6. Create the Figure .
   

fig = go.Figure(data=[candlestick], layout=layout)

7. Assign the Layout to the chart.
   

chart.WithLayout(layout);

8. Show the plot.
   

fig.show()

HTML(GenericChart.toChartHTML(chart))

The Jupyter Notebook displays a candlestick chart of the Option contract's price.

Line Chart

Follow these steps to plot line charts using built-in methods Plotly.NET package :

1. Get some historical data.

history = qb.History(OpenInterest, contract_symbol, datetime(2021, 12, 1), datetime(2021, 12, 31))

var history = qb.History<OpenInterest>(contract_symbol, new DateTime(2021, 12, 1), new DateTime(2021, 12, 31));

2. Drop the first three index levels of the DataFrame that returns.
   

history.index = history.index.droplevel([0, 1, 2])

3. Select the open interest data.

history = history['openinterest'].unstack(level=0)

4. Rename the column to the Symbol of the contract.

history.columns = [
    Symbol.GetAlias(SecurityIdentifier.Parse(x), equity_symbol)
        for x in history.columns]

5. Call the plot method with a title.

history.plot(title="Open Interest")

6. Create a Line chart.

var chart = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x.EndTime),
    history.Select(x => x.Value)
);

7. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Open Interest");
Title title = Title.init("SPY Open Interest");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

8. Assign the Layout to the chart.
   

chart.WithLayout(layout);

9. Show the plot.

plt.show()

HTML(GenericChart.toChartHTML(chart))

The Jupyter Notebook displays a line chart of open interest data.

Get Price Model Data

Follow these steps to get the values of theoretical prices, implied volatility, and Greeks:

1. Create subscriptions and set the price model .
2. Set the underlying volatility model .

qb.Securities[equity_symbol].VolatilityModel = StandardDeviationOfReturnsVolatilityModel(30, Resolution.Daily)

You need to reset the volatility before you start calculating the theoretical prices, implied volatility, and Greeks.

3. Get historical data for the underlying Equity and the Option contract(s).
4. Iterate through the historical data and calculate the values.

df = pd.DataFrame()
for slice in history:
    underlying_price = None
    underlying_volatility = None

    # Update the security with QuoteBar information
    for bar in slice.QuoteBars.Values:
        qb.Securities[bar.Symbol].SetMarketPrice(bar)

    # Update the security with TradeBar information
    for bar in slice.Bars.Values:
        symbol = bar.Symbol
        security = qb.Securities[symbol]
        security.SetMarketPrice(bar)

        if security.Type == SecurityType.Equity:
            underlying_volatility = security.VolatilityModel.Volatility
            underlying_price = security.Price
            continue
        
        # Create the Option contract
        contract = OptionContract.Create(symbol, symbol.Underlying, bar.EndTime, security, underlying_price)
        contract.LastPrice = bar.Close

        # Evaluate the price model to get the IV, Greeks, and theoretical price
        result = security.PriceModel.Evaluate(security, None, contract)
        greeks = result.Greeks
        
        # Append the data to the DataFrame
        data = {
            "IV" : result.ImpliedVolatility,
            "Delta": greeks.Delta,
            "Gamma": greeks.Gamma,
            "Vega": greeks.Vega,
            "Rho": greeks.Rho,
            "Theta": greeks.Theta,
            "LastPrice": contract.LastPrice,
            "Close": security.Close,
            "theoreticalPrice" : result.TheoreticalPrice,
            "underlyingPrice": underlying_price,
            "underlyingVolatility": underlying_volatility
        }
        right = "Put" if symbol.ID.OptionRight == 1 else "Call"
        index = pd.MultiIndex.from_tuples([(symbol.ID.Date, symbol.ID.StrikePrice, right, symbol.Value, bar.EndTime)], names=["expiry", "strike", "type", "symbol", "endTime"])
        df = pd.concat([df, pd.DataFrame(data, index=index)])

For a full example, see the following project:

Datasets > Crypto

Introduction

This page explains how to request, manipulate, and visualize historical Crypto data.

Create Subscriptions

Follow these steps to subscribe to a Crypto security:

1. Load the required assembly files and data types.

#load "../Initialize.csx"
#load "../QuantConnect.csx"
#r "../Microsoft.Data.Analysis.dll"

using QuantConnect;
using QuantConnect.Data;
using QuantConnect.Algorithm;
using QuantConnect.Research;
using Microsoft.Data.Analysis;

2. Create a QuantBook .

var qb = new QuantBook();

qb = QuantBook()

3. Call the AddCrypto method with a ticker and then save a reference to the Crypto Symbol .

var btcusd = qb.AddCrypto("BTCUSD").Symbol;
var ethusd = qb.AddCrypto("ETHUSD").Symbol;

btcusd = qb.AddCrypto("BTCUSD").Symbol
ethusd = qb.AddCrypto("ETHUSD").Symbol

To view the supported assets in the Crypto datasets, see the Supported Assets section of the CoinAPI dataset listings .

Get Historical Data

You need a subscription before you can request historical data for a security. On the time dimension, you can request an amount of historical data based on a trailing number of bars, a trailing period of time, or a defined period of time. On the security dimension, you can request historical data for a single Cryptocurrency, a subset of the Cryptocurrencies you created subscriptions for in your notebook, or all of the Cryptocurrencies in your notebook.

Trailing Number of Bars

To get historical data for a number of trailing bars, call the History method with the Symbol object(s) and an integer.

// Slice objects
var singleHistorySlice = qb.History(btcusd, 10);
var subsetHistorySlice = qb.History(new[] {btcusd, ethusd}, 10);
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(btcusd, 10);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {btcusd, ethusd}, 10);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, 10);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(btcusd, 10);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {btcusd, ethusd}, 10);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, 10);

# DataFrame of trade and quote data
single_history_df = qb.History(btcusd, 10)
subset_history_df = qb.History([btcusd, ethusd], 10)
all_history_df = qb.History(qb.Securities.Keys, 10)

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, btcusd, 10)
subset_history_trade_bar_df = qb.History(TradeBar, [btcusd, ethusd], 10)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, 10)

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, btcusd, 10)
subset_history_quote_bar_df = qb.History(QuoteBar, [btcusd, ethusd], 10)
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, 10)

# Slice objects
all_history_slice = qb.History(10)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](btcusd, 10)
subset_history_trade_bars = qb.History[TradeBar]([btcusd, ethusd], 10)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, 10)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](btcusd, 10)
subset_history_quote_bars = qb.History[QuoteBar]([btcusd, ethusd], 10)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, 10)

Trailing Period of Time

To get historical data for a trailing period of time, call the History method with the Symbol object(s) and a TimeSpan timedelta .

// Slice objects
var singleHistorySlice = qb.History(btcusd, TimeSpan.FromDays(3));
var subsetHistorySlice = qb.History(new[] {btcusd, ethusd}, TimeSpan.FromDays(3));
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(btcusd, TimeSpan.FromDays(3));
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {btcusd, ethusd}, TimeSpan.FromDays(3));
var allHistoryTradeBars = qb.History<TradeBar>(TimeSpan.FromDays(3));

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(btcusd, TimeSpan.FromDays(3), Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {btcusd, ethusd}, TimeSpan.FromDays(3), Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Minute);

// Tick objects
var singleHistoryTicks = qb.History<Tick>(btcusd, TimeSpan.FromDays(3), Resolution.Tick);
var subsetHistoryTicks = qb.History<Tick>(new[] {btcusd, ethusd}, TimeSpan.FromDays(3), Resolution.Tick);
var allHistoryTicks = qb.History<Tick>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Tick);

# DataFrame of trade and quote data
single_history_df = qb.History(btcusd, timedelta(days=3))
subset_history_df = qb.History([btcusd, ethusd], timedelta(days=3))
all_history_df = qb.History(qb.Securities.Keys, timedelta(days=3))

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, btcusd, timedelta(days=3))
subset_history_trade_bar_df = qb.History(TradeBar, [btcusd, ethusd], timedelta(days=3))
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, timedelta(days=3))

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, btcusd, timedelta(days=3))
subset_history_quote_bar_df = qb.History(QuoteBar, [btcusd, ethusd], timedelta(days=3))
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, timedelta(days=3))

# DataFrame of tick data
single_history_tick_df = qb.History(btcusd, timedelta(days=3), Resolution.Tick)
subset_history_tick_df = qb.History([btcusd, ethusd], timedelta(days=3), Resolution.Tick)
all_history_tick_df = qb.History(qb.Securities.Keys, timedelta(days=3), Resolution.Tick)

# Slice objects
all_history_slice = qb.History(timedelta(days=3))

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](btcusd, timedelta(days=3))
subset_history_trade_bars = qb.History[TradeBar]([btcusd, ethusd], timedelta(days=3))
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, timedelta(days=3))

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](btcusd, timedelta(days=3), Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([btcusd, ethusd], timedelta(days=3), Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, timedelta(days=3), Resolution.Minute)

# Tick objects
single_history_ticks = qb.History[Tick](btcusd, timedelta(days=3), Resolution.Tick)
subset_history_ticks = qb.History[Tick]([btcusd, ethusd], timedelta(days=3), Resolution.Tick)
all_history_ticks = qb.History[Tick](qb.Securities.Keys, timedelta(days=3), Resolution.Tick)

Defined Period of Time

To get historical data for a specific period of time, call the History method with the Symbol object(s), a start DateTime datetime , and an end DateTime datetime . The start and end times you provide are based in the notebook time zone .

var startTime = new DateTime(2021, 1, 1);
var endTime = new DateTime(2021, 2, 1);

// Slice objects
var singleHistorySlice = qb.History(btcusd, startTime, endTime);
var subsetHistorySlice = qb.History(new[] {btcusd, ethusd}, startTime, endTime);
var allHistorySlice = qb.History(qb.Securities.Keys, startTime, endTime);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(btcusd, startTime, endTime);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {btcusd, ethusd}, startTime, endTime);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, startTime, endTime);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(btcusd, startTime, endTime, Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {btcusd, ethusd}, startTime, endTime, Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, startTime, endTime, Resolution.Minute);

// Tick objects
var singleHistoryTicks = qb.History<Tick>(btcusd, startTime, endTime, Resolution.Tick);
var subsetHistoryTicks = qb.History<Tick>(new[] {btcusd, ethusd}, startTime, endTime, Resolution.Tick);
var allHistoryTicks = qb.History<Tick>(qb.Securities.Keys, startTime, endTime, Resolution.Tick);

start_time = datetime(2021, 1, 1)
end_time = datetime(2021, 2, 1)

# DataFrame of trade and quote data
single_history_df = qb.History(btcusd, start_time, end_time)
subset_history_df = qb.History([btcusd, ethusd], start_time, end_time)
all_history_df = qb.History(qb.Securities.Keys, start_time, end_time)

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, btcusd, start_time, end_time)
subset_history_trade_bar_df = qb.History(TradeBar, [btcusd, ethusd], start_time, end_time)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, start_time, end_time)

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, btcusd, start_time, end_time)
subset_history_quote_bar_df = qb.History(QuoteBar, [btcusd, ethusd], start_time, end_time)
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, start_time, end_time)

# DataFrame of tick data
single_history_tick_df = qb.History(btcusd, start_time, end_time, Resolution.Tick)
subset_history_tick_df = qb.History([btcusd, ethusd], start_time, end_time, Resolution.Tick)
all_history_tick_df = qb.History(qb.Securities.Keys, start_time, end_time, Resolution.Tick)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](btcusd, start_time, end_time)
subset_history_trade_bars = qb.History[TradeBar]([btcusd, ethusd], start_time, end_time)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, start_time, end_time)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](btcusd, start_time, end_time, Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([btcusd, ethusd], start_time, end_time, Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, start_time, end_time, Resolution.Minute)

# Tick objects
single_history_ticks = qb.History[Tick](btcusd, start_time, end_time, Resolution.Tick)
subset_history_ticks = qb.History[Tick]([btcusd, ethusd], start_time, end_time, Resolution.Tick)
all_history_ticks = qb.History[Tick](qb.Securities.Keys, start_time, end_time, Resolution.Tick)

Resolutions

The following table shows the available resolutions and data formats for Crypto subscriptions:

Resolution	TradeBar	QuoteBar	Trade Tick	Quote Tick
Tick
Second
Minute
Hour
Daily

Markets

The following Market enumeration members are available for Crypto:

Wrangle Data

You need some historical data to perform wrangling operations. The process to manipulate the historical data depends on its data type. To display pandas objects, run a cell in a notebook with the pandas object as the last line. To display other data formats, call the print method.

You need some historical data to perform wrangling operations. Use LINQ to wrangle the data and then call the Console.WriteLine method in a Jupyter Notebook to display the data. The process to manipulate the historical data depends on its data type.

DataFrame Objects

If the History method returns a DataFrame , the first level of the DataFrame index is the encoded Crypto Symbol and the second level is the EndTime of the data sample. The columns of the DataFrame are the data properties.

To select the historical data of a single Crypto, index the loc property of the DataFrame with the Crypto Symbol .

all_history_df.loc[btcusd]  # or all_history_df.loc['BTCUSD']

To select a column of the DataFrame , index it with the column name.

all_history_df.loc[btcusd]['close']

If you request historical data for multiple Crypto pairs, you can transform the DataFrame so that it's a time series of close values for all of the Crypto pairs. To transform the DataFrame , select the column you want to display for each Crypto pair and then call the unstack method.

all_history_df['close'].unstack(level=0)

The DataFrame is transformed so that the column indices are the Symbol of each Crypto pair and each row contains the close value.

The historical data methods don't return DataFrame objects, but you can create one for efficient vectorized data wrangling.

using Microsoft.Data.Analysis; 

var columns = new DataFrameColumn[] {
    new PrimitiveDataFrameColumn("Time", history.Select(x => x[btcusd].EndTime)),
    new DecimalDataFrameColumn("BTCUSD Open", history.Select(x => x[btcusd].Open)),
    new DecimalDataFrameColumn("BTCUSD High", history.Select(x => x[btcusd].High)),
    new DecimalDataFrameColumn("BTCUSD Low", history.Select(x => x[btcusd].Low)),
    new DecimalDataFrameColumn("BTCUSD Close", history.Select(x => x[btcusd].Close))
};
var df = new DataFrame(columns);
df

To select a particular column of the DataFrame, index it with the column name.

df["BTCUSD close"]

Slice Objects

If the History method returns Slice objects, iterate through the Slice objects to get each one. The Slice objects may not have data for all of your Crypto subscriptions. To avoid issues, check if the Slice contains data for your Crypto pair before you index it with the Crypto Symbol .

foreach (var slice in allHistorySlice) {
    if (slice.Bars.ContainsKey(btcusd))
    {
        var tradeBar = slice.Bars[btcusd];
    }
    if (slice.QuoteBars.ContainsKey(btcusd))
    {
        var quoteBar = slice.QuoteBars[btcusd];
    }
}

for slice in all_history_slice:
        if slice.Bars.ContainsKey(btcusd):
        trade_bar = slice.Bars[btcusd]
    if slice.QuoteBars.ContainsKey(btcusd):
        quote_bar = slice.QuoteBars[btcusd]

You can also iterate through each TradeBar and QuoteBar in the Slice .

foreach (var slice in allHistorySlice)
{
    foreach (var kvp in slice.Bars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
    foreach (var kvp in slice.QuoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for slice in all_history_slice:
    for kvp in slice.Bars:
        symbol = kvp.Key
        trade_bar = kvp.Value
    for kvp in slice.QuoteBars:
        symbol = kvp.Key
        quote_bar = kvp.Value

You can also use LINQ to select each TradeBar in the Slice for a given Symbol .

var tradeBars = allHistorySlice.Where(slice => slice.Bars.ContainsKey(btcusd)).Select(slice => slice.Bars[btcusd]);

TradeBar Objects

If the History method returns TradeBar objects, iterate through the TradeBar objects to get each one.

foreach (var tradeBar in singleHistoryTradeBars)
{
    Console.WriteLine(tradeBar);
}

for trade_bar in single_history_trade_bars:
    print(trade_bar)

If the History method returns TradeBars , iterate through the TradeBars to get the TradeBar of each Crypto pair. The TradeBars may not have data for all of your Crypto subscriptions. To avoid issues, check if the TradeBars object contains data for your security before you index it with the Crypto Symbol .

foreach (var tradeBars in allHistoryTradeBars)
{
    if (tradeBars.ContainsKey(btcusd))
    {
        var tradeBar = tradeBars[btcusd];
    }
}

for trade_bars in all_history_trade_bars:
    if trade_bars.ContainsKey(btcusd):
        trade_bar = trade_bars[btcusd]

You can also iterate through each of the TradeBars .

foreach (var tradeBars in allHistoryTradeBars)
{
    foreach (var kvp in tradeBars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
}

for trade_bars in all_history_trade_bars:
    for kvp in trade_bars:
        symbol = kvp.Key
        trade_bar = kvp.Value

QuoteBar Objects

If the History method returns QuoteBar objects, iterate through the QuoteBar objects to get each one.

foreach (var quoteBar in singleHistoryQuoteBars)
{
    Console.WriteLine(quoteBar);
}

for quote_bar in single_history_quote_bars:
    print(quote_bar)

If the History method returns QuoteBars , iterate through the QuoteBars to get the QuoteBar of each Crypto pair. The QuoteBars may not have data for all of your Crypto subscriptions. To avoid issues, check if the QuoteBars object contains data for your security before you index it with the Crypto Symbol .

foreach (var quoteBars in allHistoryQuoteBars)
{
    if (quoteBars.ContainsKey(btcusd))
    {
        var quoteBar = quoteBars[btcusd];
    }
}

for quote_bars in all_history_quote_bars:
    if quote_bars.ContainsKey(btcusd):
        quote_bar = quote_bars[btcusd]

You can also iterate through each of the QuoteBars .

foreach (var quoteBars in allHistoryQuoteBars)
{
    foreach (var kvp in quoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for quote_bars in all_history_quote_bars:
    for kvp in quote_bars:
        symbol = kvp.Key
        quote_bar = kvp.Value

Tick Objects

If the History method returns Tick objects, iterate through the Tick objects to get each one.

foreach (var tick in singleHistoryTicks)
{
    Console.WriteLine(tick);
}

for tick in single_history_ticks:
    print(tick)

If the History method returns Ticks , iterate through the Ticks to get the Tick of each Crypto pair. The Ticks may not have data for all of your Crypto subscriptions. To avoid issues, check if the Ticks object contains data for your security before you index it with the Crypto Symbol .

foreach (var ticks in allHistoryTicks)
{
    if (ticks.ContainsKey(btcusd))
    {
        var tick = ticks[btcusd];
    }
}

for ticks in all_history_ticks:
    if ticks.ContainsKey(btcusd):
        ticks = ticks[btcusd]

You can also iterate through each of the Ticks .

foreach (var ticks in allHistoryTicks)
{
    foreach (var kvp in ticks)
    {
        var symbol = kvp.Key;
        var tick = kvp.Value;
    }
}

for ticks in all_history_ticks:
    for kvp in ticks:
        symbol = kvp.Key
        tick = kvp.Value

Plot Data

You need some historical Crypto data to produce plots. You can use many of the supported plotting libraries Plot.NET package to visualize data in various formats. For example, you can plot candlestick and line charts.

Candlestick Chart

Follow these steps to plot candlestick charts:

1. Get some historical data.

history = qb.History(btcusd, datetime(2020, 12, 27), datetime(2021, 12, 21), Resolution.Daily).loc[btcusd]

var history = qb.History<TradeBar>(btcusd, new DateTime(2020, 12, 27), new DateTime(2021, 12, 21), Resolution.Daily);

2. Import the plotly Plotly.NET library.

import plotly.graph_objects as go

#r "../Plotly.NET.dll"
using Plotly.NET;
using Plotly.NET.LayoutObjects;

3. Create a Candlestick .
   

candlestick = go.Candlestick(x=history.index,
                             open=history['open'],
                             high=history['high'],
                             low=history['low'],
                             close=history['close'])

var chart = Chart2D.Chart.Candlestick<decimal, decimal, decimal, decimal, DateTime, string>(
    history.Select(x => x.Open),
    history.Select(x => x.High),
    history.Select(x => x.Low),
    history.Select(x => x.Close),
    history.Select(x => x.EndTime)
);

4. Create a Layout .
   

layout = go.Layout(title=go.layout.Title(text='BTCUSD OHLC'),
                   xaxis_title='Date',
                   yaxis_title='Price',
                   xaxis_rangeslider_visible=False)

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{btcusd} Price");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

5. Create the Figure .
   

fig = go.Figure(data=[candlestick], layout=layout)

6. Assign the Layout to the chart.
   

chart.WithLayout(layout);

7. Show the Figure .
   

fig.show()

HTML(GenericChart.toChartHTML(chart))

Candlestick charts display the open, high, low, and close prices of the security.

Line Chart

Follow these steps to plot line charts using built-in methods Plotly.NET package :

1. Get some historical data.

history = qb.History([btcusd, ethusd], datetime(2020, 12, 27), datetime(2021, 12, 21), Resolution.Daily)

var history = qb.History<TradeBar>(new[] {btcusd, ethusd}, new DateTime(2020, 12, 27), new DateTime(2021, 12, 21), Resolution.Daily);

2. Select the data to plot.

volume = history['volume'].unstack(level=0)

3. Call the plot method on the pandas object.

volume.plot(title="Volume", figsize=(15, 10))

4. Create Line charts.

var chart1 = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x[btcusd].EndTime),
    history.Select(x => x[btcusd].Volume),
    Name: "BTCUSD"
);
var chart2 = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x[ethusd].EndTime),
    history.Select(x => x[ethusd].Volume),
    Name: "ETHUSD"
);

5. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Volume");
Title title = Title.init("BTCUSD & ETHUSD Volume");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

6. Combine the charts and assign the Layout to the chart.
   

var chart = Plotly.NET.Chart.Combine(new []{chart1, chart2});
chart.WithLayout(layout);

7. Show the plot.

plt.show()

HTML(GenericChart.toChartHTML(chart))

Line charts display the value of the property you selected in a time series.

Datasets > Crypto Futures

Introduction

This page explains how to request, manipulate, and visualize historical Crypto Futures data.

Create Subscriptions

Follow these steps to subscribe to a perpetual Crypto Futures contract:

1. Load the required assembly files and data types.

#load "../Initialize.csx"
#load "../QuantConnect.csx"
#r "../Microsoft.Data.Analysis.dll"

using QuantConnect;
using QuantConnect.Data;
using QuantConnect.Algorithm;
using QuantConnect.Research;
using Microsoft.Data.Analysis;

2. Create a QuantBook .

var qb = new QuantBook();

qb = QuantBook()

3. Call the AddCryptoFuture method with a ticker and then save a reference to the Crypto Future Symbol .

var btcusd = qb.AddCryptoFuture("BTCUSD").Symbol;
var ethusd = qb.AddCryptoFuture("ETHUSD").Symbol;

btcusd = qb.AddCryptoFuture("BTCUSD").Symbol
ethusd = qb.AddCryptoFuture("ETHUSD").Symbol

To view the supported assets in the Crypto Futures datasets, see the Data Explorer .

Get Historical Data

You need a subscription before you can request historical data for a security. You can request an amount of historical data based on a trailing number of bars, a trailing period of time, or a defined period of time. You can also request historical data for a single contract, a subset of the contracts you created subscriptions for in your notebook, or all of the contracts in your notebook.

Trailing Number of Bars

To get historical data for a number of trailing bars, call the History method with the Symbol object(s) and an integer.

// Slice objects
var singleHistorySlice = qb.History(btcusd, 10);
var subsetHistorySlice = qb.History(new[] {btcusd, ethusd}, 10);
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(btcusd, 10);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {btcusd, ethusd}, 10);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, 10);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(btcusd, 10);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {btcusd, ethusd}, 10);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, 10);

# DataFrame of trade and quote data
single_history_df = qb.History(btcusd, 10)
subset_history_df = qb.History([btcusd, ethusd], 10)
all_history_df = qb.History(qb.Securities.Keys, 10)

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, btcusd, 10)
subset_history_trade_bar_df = qb.History(TradeBar, [btcusd, ethusd], 10)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, 10)

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, btcusd, 10)
subset_history_quote_bar_df = qb.History(QuoteBar, [btcusd, ethusd], 10)
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, 10)

# Slice objects
all_history_slice = qb.History(10)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](btcusd, 10)
subset_history_trade_bars = qb.History[TradeBar]([btcusd, ethusd], 10)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, 10)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](btcusd, 10)
subset_history_quote_bars = qb.History[QuoteBar]([btcusd, ethusd], 10)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, 10)

Trailing Period of Time

To get historical data for a trailing period of time, call the History method with the Symbol object(s) and a TimeSpan timedelta .

// Slice objects
var singleHistorySlice = qb.History(btcusd, TimeSpan.FromDays(3));
var subsetHistorySlice = qb.History(new[] {btcusd, ethusd}, TimeSpan.FromDays(3));
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(btcusd, TimeSpan.FromDays(3));
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {btcusd, ethusd}, TimeSpan.FromDays(3));
var allHistoryTradeBars = qb.History<TradeBar>(TimeSpan.FromDays(3));

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(btcusd, TimeSpan.FromDays(3), Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {btcusd, ethusd}, TimeSpan.FromDays(3), Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Minute);

// Tick objects
var singleHistoryTicks = qb.History<Tick>(btcusd, TimeSpan.FromDays(3), Resolution.Tick);
var subsetHistoryTicks = qb.History<Tick>(new[] {btcusd, ethusd}, TimeSpan.FromDays(3), Resolution.Tick);
var allHistoryTicks = qb.History<Tick>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Tick);

# DataFrame of trade and quote data
single_history_df = qb.History(btcusd, timedelta(days=3))
subset_history_df = qb.History([btcusd, ethusd], timedelta(days=3))
all_history_df = qb.History(qb.Securities.Keys, timedelta(days=3))

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, btcusd, timedelta(days=3))
subset_history_trade_bar_df = qb.History(TradeBar, [btcusd, ethusd], timedelta(days=3))
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, timedelta(days=3))

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, btcusd, timedelta(days=3))
subset_history_quote_bar_df = qb.History(QuoteBar, [btcusd, ethusd], timedelta(days=3))
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, timedelta(days=3))

# DataFrame of tick data
single_history_tick_df = qb.History(btcusd, timedelta(days=3), Resolution.Tick)
subset_history_tick_df = qb.History([btcusd, ethusd], timedelta(days=3), Resolution.Tick)
all_history_tick_df = qb.History(qb.Securities.Keys, timedelta(days=3), Resolution.Tick)

# Slice objects
all_history_slice = qb.History(timedelta(days=3))

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](btcusd, timedelta(days=3))
subset_history_trade_bars = qb.History[TradeBar]([btcusd, ethusd], timedelta(days=3))
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, timedelta(days=3))

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](btcusd, timedelta(days=3), Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([btcusd, ethusd], timedelta(days=3), Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, timedelta(days=3), Resolution.Minute)

# Tick objects
single_history_ticks = qb.History[Tick](btcusd, timedelta(days=3), Resolution.Tick)
subset_history_ticks = qb.History[Tick]([btcusd, ethusd], timedelta(days=3), Resolution.Tick)
all_history_ticks = qb.History[Tick](qb.Securities.Keys, timedelta(days=3), Resolution.Tick)

Defined Period of Time

To get historical data for a specific period of time, call the History method with the Symbol object(s), a start DateTime datetime , and an end DateTime datetime . The start and end times you provide are based in the notebook time zone .

var startTime = new DateTime(2021, 1, 1);
var endTime = new DateTime(2021, 2, 1);

// Slice objects
var singleHistorySlice = qb.History(btcusd, startTime, endTime);
var subsetHistorySlice = qb.History(new[] {btcusd, ethusd}, startTime, endTime);
var allHistorySlice = qb.History(qb.Securities.Keys, startTime, endTime);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(btcusd, startTime, endTime);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {btcusd, ethusd}, startTime, endTime);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, startTime, endTime);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(btcusd, startTime, endTime, Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {btcusd, ethusd}, startTime, endTime, Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, startTime, endTime, Resolution.Minute);

// Tick objects
var singleHistoryTicks = qb.History<Tick>(btcusd, startTime, endTime, Resolution.Tick);
var subsetHistoryTicks = qb.History<Tick>(new[] {btcusd, ethusd}, startTime, endTime, Resolution.Tick);
var allHistoryTicks = qb.History<Tick>(qb.Securities.Keys, startTime, endTime, Resolution.Tick);

start_time = datetime(2021, 1, 1)
end_time = datetime(2021, 2, 1)

# DataFrame of trade and quote data
single_history_df = qb.History(btcusd, start_time, end_time)
subset_history_df = qb.History([btcusd, ethusd], start_time, end_time)
all_history_df = qb.History(qb.Securities.Keys, start_time, end_time)

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, btcusd, start_time, end_time)
subset_history_trade_bar_df = qb.History(TradeBar, [btcusd, ethusd], start_time, end_time)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, start_time, end_time)

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, btcusd, start_time, end_time)
subset_history_quote_bar_df = qb.History(QuoteBar, [btcusd, ethusd], start_time, end_time)
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, start_time, end_time)

# DataFrame of tick data
single_history_tick_df = qb.History(btcusd, start_time, end_time, Resolution.Tick)
subset_history_tick_df = qb.History([btcusd, ethusd], start_time, end_time, Resolution.Tick)
all_history_tick_df = qb.History(qb.Securities.Keys, start_time, end_time, Resolution.Tick)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](btcusd, start_time, end_time)
subset_history_trade_bars = qb.History[TradeBar]([btcusd, ethusd], start_time, end_time)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, start_time, end_time)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](btcusd, start_time, end_time, Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([btcusd, ethusd], start_time, end_time, Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, start_time, end_time, Resolution.Minute)

# Tick objects
single_history_ticks = qb.History[Tick](btcusd, start_time, end_time, Resolution.Tick)
subset_history_ticks = qb.History[Tick]([btcusd, ethusd], start_time, end_time, Resolution.Tick)
all_history_ticks = qb.History[Tick](qb.Securities.Keys, start_time, end_time, Resolution.Tick)

Resolutions

The following table shows the available resolutions and data formats for Crypto Futures contract subscriptions:

Resolution	TradeBar	QuoteBar	Trade Tick	Quote Tick
Tick
Second
Minute
Hour
Daily

Markets

Crypto Futures are currently only available on Market.Binance .

Wrangle Data

You need some historical data to perform wrangling operations. The process to manipulate the historical data depends on its data type. To display pandas objects, run a cell in a notebook with the pandas object as the last line. To display other data formats, call the print method.

You need some historical data to perform wrangling operations. Use LINQ to wrangle the data and then call the Console.WriteLine method in a Jupyter Notebook to display the data. The process to manipulate the historical data depends on its data type.

DataFrame Objects

If the History method returns a DataFrame , the first level of the DataFrame index is the encoded Crypto Future Symbol and the second level is the EndTime of the data sample. The columns of the DataFrame are the data properties.

To select the historical data of a single Crypto Future, index the loc property of the DataFrame with the Crypto Future Symbol .

all_history_df.loc[btcusd]  # or all_history_df.loc['BTCUSD']

To select a column of the DataFrame , index it with the column name.

all_history_df.loc[btcusd]['close']

If you request historical data for multiple Crypto Futures contracts, you can transform the DataFrame so that it's a time series of close values for all of the Crypto Futures contracts. To transform the DataFrame , select the column you want to display for each Crypto Futures contract and then call the unstack method.

all_history_df['close'].unstack(level=0)

The DataFrame is transformed so that the column indices are the Symbol of each Crypto Futures contract and each row contains the close value.

The historical data methods don't return DataFrame objects, but you can create one for efficient vectorized data wrangling.

using Microsoft.Data.Analysis; 

var columns = new DataFrameColumn[] {
    new PrimitiveDataFrameColumn("Time", history.Select(x => x[btcusd].EndTime)),
    new DecimalDataFrameColumn("BTCUSD Open", history.Select(x => x[btcusd].Open)),
    new DecimalDataFrameColumn("BTCUSD High", history.Select(x => x[btcusd].High)),
    new DecimalDataFrameColumn("BTCUSD Low", history.Select(x => x[btcusd].Low)),
    new DecimalDataFrameColumn("BTCUSD Close", history.Select(x => x[btcusd].Close))
};
var df = new DataFrame(columns);
df

To select a particular column of the DataFrame, index it with the column name.

df["BTCUSD close"]

Slice Objects

If the History method returns Slice objects, iterate through the Slice objects to get each one. The Slice objects may not have data for all of your Crypto Future subscriptions. To avoid issues, check if the Slice contains data for your Crypto Futures contract before you index it with the Crypto Future Symbol .

foreach (var slice in allHistorySlice) {
    if (slice.Bars.ContainsKey(btcusd))
    {
        var tradeBar = slice.Bars[btcusd];
    }
    if (slice.QuoteBars.ContainsKey(btcusd))
    {
        var quoteBar = slice.QuoteBars[btcusd];
    }
}

for slice in all_history_slice:
        if slice.Bars.ContainsKey(btcusd):
        trade_bar = slice.Bars[btcusd]
    if slice.QuoteBars.ContainsKey(btcusd):
        quote_bar = slice.QuoteBars[btcusd]

You can also iterate through each TradeBar and QuoteBar in the Slice .

foreach (var slice in allHistorySlice)
{
    foreach (var kvp in slice.Bars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
    foreach (var kvp in slice.QuoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for slice in all_history_slice:
    for kvp in slice.Bars:
        symbol = kvp.Key
        trade_bar = kvp.Value
    for kvp in slice.QuoteBars:
        symbol = kvp.Key
        quote_bar = kvp.Value

You can also use LINQ to select each TradeBar in the Slice for a given Symbol .

var tradeBars = allHistorySlice.Where(slice => slice.Bars.ContainsKey(btcusd)).Select(slice => slice.Bars[btcusd]);

TradeBar Objects

If the History method returns TradeBar objects, iterate through the TradeBar objects to get each one.

foreach (var tradeBar in singleHistoryTradeBars)
{
    Console.WriteLine(tradeBar);
}

for trade_bar in single_history_trade_bars:
    print(trade_bar)

If the History method returns TradeBars , iterate through the TradeBars to get the TradeBar of each Crypto Futures contract. The TradeBars may not have data for all of your Crypto Future subscriptions. To avoid issues, check if the TradeBars object contains data for your security before you index it with the Crypto Future Symbol .

foreach (var tradeBars in allHistoryTradeBars)
{
    if (tradeBars.ContainsKey(btcusd))
    {
        var tradeBar = tradeBars[btcusd];
    }
}

for trade_bars in all_history_trade_bars:
    if trade_bars.ContainsKey(btcusd):
        trade_bar = trade_bars[btcusd]

You can also iterate through each of the TradeBars .

foreach (var tradeBars in allHistoryTradeBars)
{
    foreach (var kvp in tradeBars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
}

for trade_bars in all_history_trade_bars:
    for kvp in trade_bars:
        symbol = kvp.Key
        trade_bar = kvp.Value

QuoteBar Objects

If the History method returns QuoteBar objects, iterate through the QuoteBar objects to get each one.

foreach (var quoteBar in singleHistoryQuoteBars)
{
    Console.WriteLine(quoteBar);
}

for quote_bar in single_history_quote_bars:
    print(quote_bar)

If the History method returns QuoteBars , iterate through the QuoteBars to get the QuoteBar of each Crypto Futures contract. The QuoteBars may not have data for all of your Crypto Future subscriptions. To avoid issues, check if the QuoteBars object contains data for your security before you index it with the Crypto Future Symbol .

foreach (var quoteBars in allHistoryQuoteBars)
{
    if (quoteBars.ContainsKey(btcusd))
    {
        var quoteBar = quoteBars[btcusd];
    }
}

for quote_bars in all_history_quote_bars:
    if quote_bars.ContainsKey(btcusd):
        quote_bar = quote_bars[btcusd]

You can also iterate through each of the QuoteBars .

foreach (var quoteBars in allHistoryQuoteBars)
{
    foreach (var kvp in quoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for quote_bars in all_history_quote_bars:
    for kvp in quote_bars:
        symbol = kvp.Key
        quote_bar = kvp.Value

Tick Objects

If the History method returns Tick objects, iterate through the Tick objects to get each one.

foreach (var tick in singleHistoryTicks)
{
    Console.WriteLine(tick);
}

for tick in single_history_ticks:
    print(tick)

If the History method returns Ticks , iterate through the Ticks to get the Tick of each Crypto Futures contract. The Ticks may not have data for all of your Crypto Future subscriptions. To avoid issues, check if the Ticks object contains data for your security before you index it with the Crypto Future Symbol .

foreach (var ticks in allHistoryTicks)
{
    if (ticks.ContainsKey(btcusd))
    {
        var tick = ticks[btcusd];
    }
}

for ticks in all_history_ticks:
    if ticks.ContainsKey(btcusd):
        ticks = ticks[btcusd]

You can also iterate through each of the Ticks .

foreach (var ticks in allHistoryTicks)
{
    foreach (var kvp in ticks)
    {
        var symbol = kvp.Key;
        var tick = kvp.Value;
    }
}

for ticks in all_history_ticks:
    for kvp in ticks:
        symbol = kvp.Key
        tick = kvp.Value

Plot Data

You need some historical Crypto Futures data to produce plots. You can use many of the supported plotting libraries Plot.NET package to visualize data in various formats. For example, you can plot candlestick and line charts.

Candlestick Chart

Follow these steps to plot candlestick charts:

1. Get some historical data.

history = qb.History(btcusd, datetime(2021, 11, 23), datetime(2021, 12, 8), Resolution.Daily).loc[btcusd]

var history = qb.History<TradeBar>(btcusd, new DateTime(2021, 11, 23), new DateTime(2021, 12, 8), Resolution.Daily);

2. Import the plotly Plotly.NET library.

import plotly.graph_objects as go

#r "../Plotly.NET.dll"
using Plotly.NET;
using Plotly.NET.LayoutObjects;

3. Create a Candlestick .
   

candlestick = go.Candlestick(x=history.index,
                             open=history['open'],
                             high=history['high'],
                             low=history['low'],
                             close=history['close'])

var chart = Chart2D.Chart.Candlestick<decimal, decimal, decimal, decimal, DateTime, string>(
    history.Select(x => x.Open),
    history.Select(x => x.High),
    history.Select(x => x.Low),
    history.Select(x => x.Close),
    history.Select(x => x.EndTime)
);

4. Create a Layout .
   

layout = go.Layout(title=go.layout.Title(text='BTCUSD 18R OHLC'),
                   xaxis_title='Date',
                   yaxis_title='Price',
                   xaxis_rangeslider_visible=False)

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init("BTCUSD 18R OHLC");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

5. Create the Figure .
   

fig = go.Figure(data=[candlestick], layout=layout)

6. Assign the Layout to the chart.
   

chart.WithLayout(layout);

7. Show the Figure .
   

fig.show()

HTML(GenericChart.toChartHTML(chart))

Candlestick charts display the open, high, low, and close prices of the security.

Line Chart

Follow these steps to plot line charts using built-in methods Plotly.NET package :

1. Get some historical data.

history = qb.History([btcusd, ethusd], datetime(2021, 11, 23), datetime(2021, 12, 8), Resolution.Daily)

2. Select the data to plot.

volume = history['volume'].unstack(level=0)

3. Call the plot method on the pandas object.

volume.plot(title="Volume", figsize=(15, 10))

4. Create Line charts.

var chart1 = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x[btcusd].EndTime),
    history.Select(x => x[btcusd].Volume),
    Name: "BTCUSD 18R"
);
var chart2 = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x[ethusd].EndTime),
    history.Select(x => x[ethusd].Volume),
    Name: "ETHUSD 18R"
);

5. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Volume");
Title title = Title.init("BTCUSD 18R & ETHUSD 18R Volume");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

6. Combine the charts and assign the Layout to the chart.
   

var chart = Plotly.NET.Chart.Combine(new []{chart1, chart2});
chart.WithLayout(layout);

7. Show the plot.

plt.show()

HTML(GenericChart.toChartHTML(chart))

Line charts display the value of the property you selected in a time series.

Datasets > Futures

Introduction

This page explains how to request, manipulate, and visualize historical Futures data.

Create Subscriptions

Follow these steps to subscribe to a Future security:

1. Load the required assembly files and data types.

#load "../Initialize.csx"
#load "../QuantConnect.csx"
#r "../Microsoft.Data.Analysis.dll"

using QuantConnect;
using QuantConnect.Data;
using QuantConnect.Data.Market;
using QuantConnect.Algorithm;
using QuantConnect.Securities;
using QuantConnect.Securities.Future;
using QuantConnect.Research;
using Microsoft.Data.Analysis;

2. Create a QuantBook .

var qb = new QuantBook();

qb = QuantBook()

3. Call the AddFuture method with a ticker, resolution, and contract rollover settings .

var future = qb.AddFuture(Futures.Indices.SP500EMini, Resolution.Minute,
                dataNormalizationMode: DataNormalizationMode.BackwardsRatio,
                dataMappingMode: DataMappingMode.LastTradingDay,
                contractDepthOffset: 0);

future = qb.AddFuture(Futures.Indices.SP500EMini, Resolution.Minute,
                dataNormalizationMode = DataNormalizationMode.BackwardsRatio,
                dataMappingMode = DataMappingMode.LastTradingDay,
                contractDepthOffset = 0)

To view the available tickers in the US Futures dataset, see Supported Assets .

If you omit any of the arguments after the ticker, see the following table for their default values:

Argument	Default Value
resolution	Resolution.Minute
dataNormalizationMode	DataNormalizationMode.Adjusted
dataMappingMode	DataMappingMode.OpenInterest
contractDepthOffset	0

4. (Optional) Set a contract filter .

future.SetFilter(0, 90);

future.SetFilter(0, 90)

If you don't call the SetFilter method, the GetFutureHistory method won't return historical data.

If you want historical data on individual contracts and their OpenInterest , follow these steps to subscribe to individual Future contracts:

1. Call the GetFuturesContractList method with the underlying Future Symbol and a datetime DateTime .

var startDate = new DateTime(2021,12,20);
var symbols = qb.FutureChainProvider.GetFutureContractList(future.Symbol, startDate);

start_date = datetime(2021,12,20)
symbols = qb.FutureChainProvider.GetFutureContractList(future.Symbol, start_date)

This method returns a list of Symbol objects that reference the Future contracts that were trading at the given time. If you set a contract filter with SetFilter , it doesn't affect the results of GetFutureContractList .

2. Select the Symbol of the FutureContract object(s) for which you want to get historical data.

For example, select the Symbol of the contract with the closest expiry.


var contractSymbol = symbols.OrderBy(s => s.ID.Date).FirstOrDefault();

contract_symbol = sorted(symbols, key=lambda s: s.ID.Date)[0]

3. Call the AddFutureContract method with an FutureContract Symbol and disable fill-forward.

qb.AddFutureContract(contractSymbol, fillForward: false);

qb.AddFutureContract(contract_symbol, fillForward = False)

Disable fill-forward because there are only a few OpenInterest data points per day.

Get Historical Data

You need a subscription before you can request historical data for Futures contracts. On the time dimension, you can request an amount of historical data based on a trailing number of bars, a trailing period of time, or a defined period of time. On the contract dimension, you can request historical data for a single contract, a subset of the contracts you created subscriptions for in your notebook, or all of the contracts in your notebook.

Before you request historical data, call the SetStartDate method with a datetime DateTime to reduce the risk of look-ahead bias .

qb.SetStartDate(startDate);

qb.SetStartDate(start_date)

If you call the SetStartDate method, the date that you pass to the method is the latest date for which your history requests will return data.

Trailing Number of Bars

To get historical data for a number of trailing bars, call the History method with the contract Symbol object(s) and an integer.

// Slice objects
var singleHistorySlice = qb.History(contractSymbol, 10);
var subsetHistorySlice = qb.History(new[] {contractSymbol}, 10);
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(contractSymbol, 10);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {contractSymbol}, 10);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, 10);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(contractSymbol, 10);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {contractSymbol}, 10);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, 10);

// OpenInterest objects
var singleHistoryOpenInterest = qb.History<OpenInterest>(contractSymbol, 400);
var subsetHistoryOpenInterest = qb.History<OpenInterest>(new[] {contractSymbol}, 400);
var allHistoryOpenInterest = qb.History<OpenInterest>(qb.Securities.Keys, 400);

# DataFrame of trade and quote data
single_history_df = qb.History(contract_symbol, 10)
subset_history_df = qb.History([contract_symbol], 10)
all_history_df = qb.History(qb.Securities.Keys, 10)

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, contract_symbol, 10)
subset_history_trade_bar_df = qb.History(TradeBar, [contract_symbol], 10)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, 10)

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, contract_symbol, 10)
subset_history_quote_bar_df = qb.History(QuoteBar, [contract_symbol], 10)
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, 10)

# DataFrame of open interest data
single_history_open_interest_df = qb.History(OpenInterest, contract_symbol, 400)
subset_history_open_interest_df = qb.History(OpenInterest, [contract_symbol], 400)
all_history_open_interest_df = qb.History(OpenInterest, qb.Securities.Keys, 400)

# Slice objects
all_history_slice = qb.History(10)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](contract_symbol, 10)
subset_history_trade_bars = qb.History[TradeBar]([contract_symbol], 10)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, 10)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](contract_symbol, 10)
subset_history_quote_bars = qb.History[QuoteBar]([contract_symbol], 10)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, 10)

# OpenInterest objects
single_history_open_interest = qb.History[OpenInterest](contract_symbol, 400)
subset_history_open_interest = qb.History[OpenInterest]([contract_symbol], 400)
all_history_open_interest = qb.History[OpenInterest](qb.Securities.Keys, 400)

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

To get historical data for the continous Futures contract, in the preceding history requests, replace contract_symbol contractSymbol with future.Symbol .

Trailing Period of Time

To get historical data for a trailing period of time, call the History method with the contract Symbol object(s) and a TimeSpan timedelta .

// Slice objects
var singleHistorySlice = qb.History(contractSymbol, TimeSpan.FromDays(3));
var subsetHistorySlice = qb.History(new[] {contractSymbol}, TimeSpan.FromDays(3));
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(contractSymbol, TimeSpan.FromDays(3));
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {contractSymbol}, TimeSpan.FromDays(3));
var allHistoryTradeBars = qb.History<TradeBar>(TimeSpan.FromDays(3));

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(contractSymbol, TimeSpan.FromDays(3), Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {contractSymbol}, TimeSpan.FromDays(3), Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Minute);

// Tick objects
var singleHistoryTicks = qb.History(contractSymbol, TimeSpan.FromDays(3), Resolution.Tick);
var subsetHistoryTicks = qb.History(new[] {contractSymbol}, TimeSpan.FromDays(3), Resolution.Tick);
var allHistoryTicks = qb.History(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Tick);

// OpenInterest objects
var singleHistoryOpenInterest = qb.History<OpenInterest>(contractSymbol, TimeSpan.FromDays(2));
var subsetHistoryOpenInterest = qb.History<OpenInterest>(new[] {contractSymbol}, TimeSpan.FromDays(2));
var allHistoryOpenInterest = qb.History<OpenInterest>(qb.Securities.Keys, TimeSpan.FromDays(2));

# DataFrame of trade and quote data
single_history_df = qb.History(contract_symbol, timedelta(days=3))
subset_history_df = qb.History([contract_symbol], timedelta(days=3))
all_history_df = qb.History(qb.Securities.Keys, timedelta(days=3))

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, contract_symbol, timedelta(days=3))
subset_history_trade_bar_df = qb.History(TradeBar, [contract_symbol], timedelta(days=3))
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, timedelta(days=3))

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, contract_symbol, timedelta(days=3))
subset_history_quote_bar_df = qb.History(QuoteBar, [contract_symbol], timedelta(days=3))
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, timedelta(days=3))

# DataFrame of open interest data
single_history_open_interest_df = qb.History(OpenInterest, contract_symbol, timedelta(days=3))
subset_history_open_interest_df = qb.History(OpenInterest, [contract_symbol], timedelta(days=3))
all_history_open_interest_df = qb.History(OpenInterest, qb.Securities.Keys, timedelta(days=3))

# Slice objects
all_history_slice = qb.History(timedelta(days=3))

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](contract_symbol, timedelta(days=3))
subset_history_trade_bars = qb.History[TradeBar]([contract_symbol], timedelta(days=3))
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, timedelta(days=3))

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](contract_symbol, timedelta(days=3), Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([contract_symbol], timedelta(days=3), Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, timedelta(days=3), Resolution.Minute) 

# Tick objects
single_history_ticks = qb.History[Tick](contract_symbol, timedelta(days=3), Resolution.Tick)
subset_history_ticks = qb.History[Tick]([contract_symbol], timedelta(days=3), Resolution.Tick)
all_history_ticks = qb.History[Tick](qb.Securities.Keys, timedelta(days=3), Resolution.Tick)

# OpenInterest objects
single_history_open_interest = qb.History[OpenInterest](contract_symbol, timedelta(days=2))
subset_history_open_interest = qb.History[OpenInterest]([contract_symbol], timedelta(days=2))
all_history_open_interest = qb.History[OpenInterest](qb.Securities.Keys, timedelta(days=2))

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

To get historical data for the continous Futures contract, in the preceding history requests, replace contract_symbol contractSymbol with future.Symbol .

Defined Period of Time

To get historical data for individual Futures contracts during a specific period of time, call the History method with the Futures contract Symbol object(s), a start DateTime datetime , and an end DateTime datetime . The start and end times you provide are based in the notebook time zone .

var startTime = new DateTime(2021, 12, 1);
var endTime = new DateTime(2021, 12, 31);

// Slice objects
var singleHistorySlice = qb.History(contractSymbol, startTime, endTime);
var subsetHistorySlice = qb.History(new[] {contractSymbol}, startTime, endTime);
var allHistorySlice = qb.History(startTime, endTime);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(contractSymbol, startTime, endTime);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {contractSymbol}, startTime, endTime);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, startTime, endTime);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(contractSymbol, startTime, endTime, Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {contractSymbol}, startTime, endTime, Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, startTime, endTime, Resolution.Minute);

// Tick objects
var singleHistoryTicks = qb.History(contractSymbol, startTime, endTime, Resolution.Tick);
var subsetHistoryTicks = qb.History(new[] {contractSymbol}, startTime, endTime, Resolution.Tick);
var allHistoryTicks = qb.History(qb.Securities.Keys, startTime, endTime, Resolution.Tick);

// OpenInterest objects
var singleHistoryOpenInterest = qb.History<OpenInterest>(contractSymbol, startTime, endTime);
var subsetHistoryOpenInterest = qb.History<OpenInterest>(new[] {contractSymbol}, startTime, endTime);
var allHistoryOpenInterest = qb.History<OpenInterest>(qb.Securities.Keys, startTime, endTime);

start_time = datetime(2021, 12, 1)
end_time = datetime(2021, 12, 31)

# DataFrame of trade and quote data
single_history_df = qb.History(contract_symbol, start_time, end_time)
subset_history_df = qb.History([contract_symbol], start_time, end_time)
all_history_df = qb.History(qb.Securities.Keys, start_time, end_time)

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, contract_symbol, start_time, end_time)
subset_history_trade_bar_df = qb.History(TradeBar, [contract_symbol], start_time, end_time)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, start_time, end_time)

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, contract_symbol, start_time, end_time)
subset_history_quote_bar_df = qb.History(QuoteBar, [contract_symbol], start_time, end_time)
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, start_time, end_time)

# DataFrame of open interest data
single_history_open_interest_df = qb.History(OpenInterest, contract_symbol, start_time, end_time)
subset_history_open_interest_df = qb.History(OpenInterest, [contract_symbol], start_time, end_time)
all_history_trade_open_interest_df = qb.History(OpenInterest, qb.Securities.Keys, start_time, end_time)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](contract_symbol, start_time, end_time)
subset_history_trade_bars = qb.History[TradeBar]([contract_symbol], start_time, end_time)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, start_time, end_time)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](contract_symbol, start_time, end_time, Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([contract_symbol], start_time, end_time, Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, start_time, end_time, Resolution.Minute)

# Tick objects
single_history_ticks = qb.History[Tick](contract_symbol, start_time, end_time, Resolution.Tick)
subset_history_ticks = qb.History[Tick]([contract_symbol], start_time, end_time, Resolution.Tick)
all_history_ticks = qb.History[Tick](qb.Securities.Keys, start_time, end_time, Resolution.Tick)

# OpenInterest objects
single_history_open_interest = qb.History[OpenInterest](contract_symbol, start_time, end_time)
subset_history_open_interest = qb.History[OpenInterest]([contract_symbol], start_time, end_time)
all_history_open_interest = qb.History[OpenInterest](qb.Securities.Keys, start_time, end_time)

To get historical data for the continous Futures contract, in the preceding history requests, replace contract_symbol contractSymbol with future.Symbol .

To get historical data for all of the Futures contracts that pass your filter during a specific period of time, call the GetFutureHistory method with the Symbol object of the continuous Future, a start DateTime datetime , and an end DateTime datetime .

future_history = qb.GetFutureHistory(future.Symbol, end_time-timedelta(days=2), end_time, Resolution.Minute, fillForward=False, extendedMarketHours=False)

var futureHistory = qb.GetFutureHistory(future.Symbol, endTime-TimeSpan.FromDays(2), endTime, Resolution.Minute, fillForward: False, extendedMarketHours: False);

The preceding calls return data that have a timestamp within the defined period of time.

Resolutions

The following table shows the available resolutions and data formats for Futures subscriptions:

Resolution	TradeBar	QuoteBar	Trade Tick	Quote Tick
Tick
Second
Minute
Hour
Daily

Markets

The following Market enumeration members are available for Futures:

Wrangle Data

You need some historical data to perform wrangling operations. The process to manipulate the historical data depends on its data type. To display pandas objects, run a cell in a notebook with the pandas object as the last line. To display other data formats, call the print method.

You need some historical data to perform wrangling operations. Use LINQ to wrangle the data and then call the Console.WriteLine method in a Jupyter Notebook to display the data. The process to manipulate the historical data depends on its data type.

DataFrame Objects

If your history request returns a DataFrame , the DataFrame has the following index levels:

1. Contract expiry
2. Encoded contract Symbol
3. The EndTime of the data sample

The columns of the DataFrame are the data properties. Depending on how you request data, the DataFrame may contain data for the continuous Futures contract. The continuous contract doesn't expire, so the default expiry date of December 30, 1899 doesn't have any practical meaning.

To select the rows of the contract(s) that expire at a specific time, index the loc property of the DataFrame with the expiry time.

all_history_df.loc[datetime(2022, 3, 18, 13, 30)]

If you remove the first index level, you can index the DataFrame with just the contract Symbol , similiar to how you would with non-derivative asset classes. To remove the first index level, call the droplevel method.

all_history_df.index = all_history_df.index.droplevel(0)

To select the historical data of a single Futures contract, index the loc property of the DataFrame with the contract Symbol .

all_history_df.loc[contract_symbol]

To select a column of the DataFrame , index it with the column name.

all_history_df.loc[contract_symbol]['close']

If you request historical data for multiple Futures contracts, you can transform the DataFrame so that it's a time series of close values for all of the Futures contracts. To transform the DataFrame , select the column you want to display for each Futures contract and then call the unstack method.

all_history_df['close'].unstack(level=0)

The DataFrame is transformed so that the column indices are the Symbol of each security and each row contains the close value.

The historical data methods don't return DataFrame objects, but you can create one for efficient vectorized data wrangling.

using Microsoft.Data.Analysis; 

var columns = new DataFrameColumn[] {
    new PrimitiveDataFrameColumn("Time", history.Select(x => x[contractSymbol].EndTime)),
    new DecimalDataFrameColumn(" Open", history.Select(x => x[contractSymbol].Open)),
    new DecimalDataFrameColumn(" High", history.Select(x => x[contractSymbol].High)),
    new DecimalDataFrameColumn(" Low", history.Select(x => x[contractSymbol].Low)),
    new DecimalDataFrameColumn(" Close", history.Select(x => x[contractSymbol].Close))
};
var df = new DataFrame(columns);
df

To select a particular column of the DataFrame, index it with the column name.

df[" close"]

Slice Objects

If the History method returns Slice objects, iterate through the Slice objects to get each one. The Slice objects may not have data for all of your Futures subscriptions. To avoid issues, check if the Slice contains data for your Futures contract before you index it with the Futures Symbol .

foreach (var slice in allHistorySlice) {
    if (slice.Bars.ContainsKey(contractSymbol))
    {
        var tradeBar = slice.Bars[contractSymbol];
    }
    if (slice.QuoteBars.ContainsKey(contractSymbol))
    {
        var quoteBar = slice.QuoteBars[contractSymbol];
    }
}

for slice in all_history_slice:
        if slice.Bars.ContainsKey(contract_symbol):
        trade_bar = slice.Bars[contract_symbol]
    if slice.QuoteBars.ContainsKey(contract_symbol):
        quote_bar = slice.QuoteBars[contract_symbol]

You can also iterate through each TradeBar and QuoteBar in the Slice .

foreach (var slice in allHistorySlice)
{
    foreach (var kvp in slice.Bars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
    foreach (var kvp in slice.QuoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for slice in all_history_slice:
    for kvp in slice.Bars:
        symbol = kvp.Key
        trade_bar = kvp.Value
    for kvp in slice.QuoteBars:
        symbol = kvp.Key
        quote_bar = kvp.Value

You can also use LINQ to select each TradeBar in the Slice for a given Symbol .

var tradeBars = allHistorySlice.Where(slice => slice.Bars.ContainsKey(contractSymbol)).Select(slice => slice.Bars[contractSymbol]);

TradeBar Objects

If the History method returns TradeBar objects, iterate through the TradeBar objects to get each one.

foreach (var tradeBar in singleHistoryTradeBars)
{
    Console.WriteLine(tradeBar);
}

for trade_bar in single_history_trade_bars:
    print(trade_bar)

If the History method returns TradeBars , iterate through the TradeBars to get the TradeBar of each Futures contract. The TradeBars may not have data for all of your Futures subscriptions. To avoid issues, check if the TradeBars object contains data for your security before you index it with the Futures Symbol .

foreach (var tradeBars in allHistoryTradeBars)
{
    if (tradeBars.ContainsKey(contractSymbol))
    {
        var tradeBar = tradeBars[contractSymbol];
    }
}

for trade_bars in all_history_trade_bars:
    if trade_bars.ContainsKey(contract_symbol):
        trade_bar = trade_bars[contract_symbol]

You can also iterate through each of the TradeBars .

foreach (var tradeBars in allHistoryTradeBars)
{
    foreach (var kvp in tradeBars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
}

for trade_bars in all_history_trade_bars:
    for kvp in trade_bars:
        symbol = kvp.Key
        trade_bar = kvp.Value

QuoteBar Objects

If the History method returns QuoteBar objects, iterate through the QuoteBar objects to get each one.

foreach (var quoteBar in singleHistoryQuoteBars)
{
    Console.WriteLine(quoteBar);
}

for quote_bar in single_history_quote_bars:
    print(quote_bar)

If the History method returns QuoteBars , iterate through the QuoteBars to get the QuoteBar of each Futures contract. The QuoteBars may not have data for all of your Futures subscriptions. To avoid issues, check if the QuoteBars object contains data for your security before you index it with the Futures Symbol .

foreach (var quoteBars in allHistoryQuoteBars)
{
    if (quoteBars.ContainsKey(contractSymbol))
    {
        var quoteBar = quoteBars[contractSymbol];
    }
}

for quote_bars in all_history_quote_bars:
    if quote_bars.ContainsKey(contract_symbol):
        quote_bar = quote_bars[contract_symbol]

You can also iterate through each of the QuoteBars .

foreach (var quoteBars in allHistoryQuoteBars)
{
    foreach (var kvp in quoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for quote_bars in all_history_quote_bars:
    for kvp in quote_bars:
        symbol = kvp.Key
        quote_bar = kvp.Value

Tick Objects

If the History method returns Tick objects, iterate through the Tick objects to get each one.

foreach (var tick in singleHistoryTicks)
{
    Console.WriteLine(tick);
}

for tick in single_history_ticks:
    print(tick)

If the History method returns Ticks , iterate through the Ticks to get the Tick of each Futures contract. The Ticks may not have data for all of your Futures subscriptions. To avoid issues, check if the Ticks object contains data for your security before you index it with the Futures Symbol .

foreach (var ticks in allHistoryTicks)
{
    if (ticks.ContainsKey(contractSymbol))
    {
        var tick = ticks[contractSymbol];
    }
}

for ticks in all_history_ticks:
    if ticks.ContainsKey(contract_symbol):
        ticks = ticks[contract_symbol]

You can also iterate through each of the Ticks .

foreach (var ticks in allHistoryTicks)
{
    foreach (var kvp in ticks)
    {
        var symbol = kvp.Key;
        var tick = kvp.Value;
    }
}

for ticks in all_history_ticks:
    for kvp in ticks:
        symbol = kvp.Key
        tick = kvp.Value

OpenInterest Objects

If the History method returns OpenInterest objects, iterate through the OpenInterest objects to get each one.

foreach (var openInterest in singleHistoryOpenInterest)
{
    Console.WriteLine(openInterest);
}

for open_interest in single_history_open_interest:
    print(open_interest)

If the History method returns a dictionary of OpenInterest objects, iterate through the dictionary to get the OpenInterest of each Futures contract. The dictionary of OpenInterest objects may not have data for all of your Futures contract subscriptions. To avoid issues, check if the dictionary contains data for your contract before you index it with the Futures contract Symbol .

foreach (var openInterestDict in allHistoryOpenInterest)
{
    if (openInterestDict.ContainsKey(contractSymbol))
    {
        var openInterest = openInterestDict[contractSymbol];
    }
}

for open_interest_dict in all_history_open_interest:
    if open_interest_dict.ContainsKey(contract_symbol):
        open_interest = open_interest_dict[contract_symbol]

You can also iterate through each of the OpenInterest dictionaries.

foreach (var openInterestDict in allHistoryOpenInterest)
{
    foreach (var kvp in openInterestDict)
    {
        var symbol = kvp.Key;
        var openInterest = kvp.Value;
    }
}

for open_interest_dict in all_history_open_interest:
    for kvp in open_interest_dict:
        symbol = kvp.Key
        open_interest = kvp.Value

FutureHistory Objects

The GetFutureHistory method returns a FutureHistory object. To get each slice in the FutureHistory object, iterate through it.

foreach (var slice in futureHistory)
{
    foreach (var kvp in slice.FuturesChains)
    {
        var continuousContractSymbol = kvp.Key;
        var chain = kvp.Value;
        foreach (var contract in chain)
        {
            
        }
    }
}

for slice in future_history:
    for continuous_contract_symbol, chain in slice.FuturesChains.items(): 
        for contract in chain:
            pass

To convert the FutureHistory object to a DataFrame that contains the trade and quote information of each contract, call the GetAllData method.

future_history.GetAllData()

To get the expiration dates of all the contracts in an FutureHistory object, call the GetExpiryDates method.

future_history.GetExpiryDates()

Plot Data

You need some historical Futures data to produce plots. You can use many of the supported plotting libraries Plot.NET package to visualize data in various formats. For example, you can plot candlestick and line charts.

Candlestick Chart

Follow these steps to plot candlestick charts:

1. Get some historical data.

history = qb.History(contract_symbol, datetime(2021, 12, 1), datetime(2021, 12, 31), Resolution.Daily)

var history = qb.History<TradeBar>(contractSymbol, new DateTime(2021, 12, 1), new DateTime(2021, 12, 31), Resolution.Daily);

2. Drop the first two index levels.

history.index = history.index.droplevel([0, 1])

3. Import the plotly Plotly.NET library.

import plotly.graph_objects as go

#r "../Plotly.NET.dll"
using Plotly.NET;
using Plotly.NET.LayoutObjects;

4. Create a Candlestick .
   

candlestick = go.Candlestick(x=history.index,
                             open=history['open'],
                             high=history['high'],
                             low=history['low'],
                             close=history['close'])

var chart = Chart2D.Chart.Candlestick<decimal, decimal, decimal, decimal, DateTime, string>(
    history.Select(x => x.Open),
    history.Select(x => x.High),
    history.Select(x => x.Low),
    history.Select(x => x.Close),
    history.Select(x => x.EndTime)
);

5. Create a Layout .
   

layout = go.Layout(title=go.layout.Title(text=f'{contract_symbol.Value} OHLC'),
                   xaxis_title='Date',
                   yaxis_title='Price',
                   xaxis_rangeslider_visible=False)

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{contractSymbol} OHLC");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

6. Create the Figure .
   

fig = go.Figure(data=[candlestick], layout=layout)

7. Assign the Layout to the chart.
   

chart.WithLayout(layout);

8. Show the Figure .
   

fig.show()

HTML(GenericChart.toChartHTML(chart))

Candlestick charts display the open, high, low, and close prices of the contract.

Line Chart

Follow these steps to plot line charts using built-in methods Plotly.NET package :

1. Get some historical data.

history = qb.History(symbols, datetime(2021, 12, 1), datetime(2021, 12, 31), Resolution.Daily)

var history = qb.History<OpenInterest>(contractSymbol, new DateTime(2021, 12, 1), new DateTime(2021, 12, 31));

2. Drop the first index level.

history.index = history.index.droplevel(0)

3. Select data to plot.

closing_prices = history['close'].unstack(level=0)

4. Rename the columns to be the Symbol of each contract.

closing_prices.columns = [Symbol.GetAlias(SecurityIdentifier.Parse(x)) for x in closing_prices.columns]

5. Call the plot method on the pandas object.

closing_prices.plot(title="Close", figsize=(15, 8))

6. Create Line charts.

var chart = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x.EndTime),
    history.Select(x => x.Value)
);

7. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Open Interest");
Title title = Title.init($"{contractSymbol} Open Interest");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

8. Assign the Layout to the chart.
   

chart.WithLayout(layout);

9. Show the plot.

plt.show()

HTML(GenericChart.toChartHTML(chart))

Line charts display the value of the property you selected in a time series.

Datasets > Futures Options

Introduction

This page explains how to request, manipulate, and visualize historical Future Options data.

Create Subscriptions

Follow these steps to subscribe to a Futures Option contract:

1. Load the required assembly files and data types.

#load "../Initialize.csx"
#load "../QuantConnect.csx"
#r "../Microsoft.Data.Analysis.dll"

using QuantConnect;
using QuantConnect.Data;
using QuantConnect.Data.Market;
using QuantConnect.Algorithm;
using QuantConnect.Securities;
using QuantConnect.Securities.Future;
using QuantConnect.Research;
using Microsoft.Data.Analysis;

2. Create a QuantBook .

var qb = new QuantBook();

qb = QuantBook()

3. Subscribe to a Futures contract .

var future = qb.AddFuture(Futures.Indices.SP500EMini, Resolution.Minute);
var startDate = new DateTime(2021,12,20);
var futuresContractSymbols = qb.FutureChainProvider.GetFutureContractList(future.Symbol, startDate);
var futuresContractSymbol = futuresContractSymbols.OrderBy(s => s.ID.Date).FirstOrDefault();
qb.AddFutureContract(futuresContractSymbol, fillForward: false);

future = qb.AddFuture(Futures.Indices.SP500EMini, Resolution.Minute)
start_date = datetime(2021,12,20)
futures_contract_symbols = qb.FutureChainProvider.GetFutureContractList(future.Symbol, start_date)
futures_contract_symbol = sorted(futures_contract_symbols, key=lambda s: s.ID.Date)[0]
qb.AddFutureContract(futures_contract_symbol, fillForward = False)

To view the available underlying Futures in the US Future Options dataset, see Supported Assets .

4. (Optional) Set a contract filter .

qb.AddFutureOption(future.Symbol, optionFilterUniverse => optionFilterUniverse.Strikes(-1, 1));

qb.AddFutureOption(future.Symbol, lambda option_filter_universe: option_filter_universe.Strikes(-1, 1))

The filter determines which contracts the GetOptionHistory method returns. If you don't set a filter, the default filter selects the contracts that have the following characteristics:

• Standard type (exclude weeklys)
• Within 1 strike price of the underlying asset price
• Expire within 31 days

If you want historical data on individual contracts and their OpenInterest , follow these steps to subscribe to the individual Futures Option contracts:

1. Call the GetOptionsContractList method with the underlying Futures Contract Symbol and a datetime DateTime object.

var fopContractSymbols = qb.OptionChainProvider.GetOptionContractList(futuresContractSymbol, startDate);

fop_contract_symbols = qb.OptionChainProvider.GetOptionContractList(futures_contract_symbol, start_date)

This method returns a list of Symbol objects that reference the Option contracts that were trading for the underlying Future contract at the given time. If you set a contract filter with SetFilter , it doesn't affect the results of GetOptionContractList .

2. Select the Symbol of the OptionContract object(s) for which you want to get historical data.

To filter and select contracts, you can use the following properties of each Symbol object:

Property	Description
ID.Date	The expiration date of the contract.
ID.StrikePrice	The strike price of the contract.
ID.OptionRight	The contract type. The OptionRight enumeration has the following members:
ID.OptionStyle	The contract style. The OptionStyle enumeration has the following members:

var closestExpiry = fopContractSymbols.Select(c => c.ID.Date).Min();
var fopContractSymbol = fopContractSymbols
    .Where(c => c.ID.Date == closestExpiry && c.ID.OptionRight == OptionRight.Call)
    .OrderBy(c => c.ID.StrikePrice)
    .FirstOrDefault();

closest_expiry = min([c.ID.Date for c in fop_contract_symbols])
calls = [c for c in fop_contract_symbols if c.ID.Date == closest_expiry and c.ID.OptionRight == OptionRight.Call]
fop_contract_symbol = sorted(calls, key=lambda c: c.ID.StrikePrice)[0]

3. Call the AddFutureOptionContract method with an OptionContract Symbol and disable fill-forward.

qb.AddFutureOptionContract(fopContractSymbol, fillForward: false);

qb.AddFutureOptionContract(fop_contract_symbol, fillForward = False)

Disable fill-forward because there are only a few OpenInterest data points per day.

Get Historical Data

You need a subscription before you can request historical data for Futures Option contracts. On the time dimension, you can request an amount of historical data based on a trailing number of bars, a trailing period of time, or a defined period of time. On the contract dimension, you can request historical data for a single contract, a subset of the contracts you created subscriptions for in your notebook, or all of the contracts in your notebook.

Before you request historical data, call the SetStartDate method with a datetime DateTime to reduce the risk of look-ahead bias .

qb.SetStartDate(startDate);

qb.SetStartDate(start_date)

If you call the SetStartDate method, the date that you pass to the method is the latest date for which your history requests will return data.

Trailing Number of Bars

To get historical data for a number of trailing bars, call the History method with the contract Symbol object(s) and an integer.

// Slice objects
var singleHistorySlice = qb.History(fopContractSymbol, 10);
var subsetHistorySlice = qb.History(new[] {fopContractSymbol}, 10);
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(fopContractSymbol, 10);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {fopContractSymbol}, 10);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, 10);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(fopContractSymbol, 10);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {fopContractSymbol}, 10);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, 10);

// OpenInterest objects
var singleHistoryOpenInterest = qb.History<OpenInterest>(fopContractSymbol, 400);
var subsetHistoryOpenInterest = qb.History<OpenInterest>(new[] {fopContractSymbol}, 400);
var allHistoryOpenInterest = qb.History<OpenInterest>(qb.Securities.Keys, 400);

# DataFrame of trade and quote data
single_history_df = qb.History(fop_contract_symbol, 10)
subset_history_df = qb.History([fop_contract_symbol], 10)
all_history_df = qb.History(qb.Securities.Keys, 10)

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, fop_contract_symbol, 10)
subset_history_trade_bar_df = qb.History(TradeBar, [fop_contract_symbol], 10)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, 10)

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, fop_contract_symbol, 10)
subset_history_quote_bar_df = qb.History(QuoteBar, [fop_contract_symbol], 10)
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, 10)

# DataFrame of open interest data
single_history_open_interest_df = qb.History(OpenInterest, fop_contract_symbol, 400)
subset_history_open_interest_df = qb.History(OpenInterest, [fop_contract_symbol], 400)
all_history_open_interest_df = qb.History(OpenInterest, qb.Securities.Keys, 400)

# Slice objects
all_history_slice = qb.History(10)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](fop_contract_symbol, 10)
subset_history_trade_bars = qb.History[TradeBar]([fop_contract_symbol], 10)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, 10)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](fop_contract_symbol, 10)
subset_history_quote_bars = qb.History[QuoteBar]([fop_contract_symbol], 10)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, 10)

# OpenInterest objects
single_history_open_interest = qb.History[OpenInterest](fop_contract_symbol, 400)
subset_history_open_interest = qb.History[OpenInterest]([fop_contract_symbol], 400)
all_history_open_interest = qb.History[OpenInterest](qb.Securities.Keys, 400)

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

Trailing Period of Time

To get historical data for a trailing period of time, call the History method with the contract Symbol object(s) and a TimeSpan timedelta .

// Slice objects
var singleHistorySlice = qb.History(fopContractSymbol, TimeSpan.FromDays(3));
var subsetHistorySlice = qb.History(new[] {fopContractSymbol}, TimeSpan.FromDays(3));
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(fopContractSymbol, TimeSpan.FromDays(3));
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {fopContractSymbol}, TimeSpan.FromDays(3));
var allHistoryTradeBars = qb.History<TradeBar>(TimeSpan.FromDays(3));

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(fopContractSymbol, TimeSpan.FromDays(3), Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {fopContractSymbol}, TimeSpan.FromDays(3), Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Minute);


// OpenInterest objects
var singleHistoryOpenInterest = qb.History<OpenInterest>(fopContractSymbol, TimeSpan.FromDays(2));
var subsetHistoryOpenInterest = qb.History<OpenInterest>(new[] {fopContractSymbol}, TimeSpan.FromDays(2));
var allHistoryOpenInterest = qb.History<OpenInterest>(qb.Securities.Keys, TimeSpan.FromDays(2));

# DataFrame of trade and quote data
single_history_df = qb.History(fop_contract_symbol, timedelta(days=3))
subset_history_df = qb.History([fop_contract_symbol], timedelta(days=3))
all_history_df = qb.History(qb.Securities.Keys, timedelta(days=3))

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, fop_contract_symbol, timedelta(days=3))
subset_history_trade_bar_df = qb.History(TradeBar, [fop_contract_symbol], timedelta(days=3))
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, timedelta(days=3))

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, fop_contract_symbol, timedelta(days=3))
subset_history_quote_bar_df = qb.History(QuoteBar, [fop_contract_symbol], timedelta(days=3))
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, timedelta(days=3))

# DataFrame of open interest data
single_history_open_interest_df = qb.History(OpenInterest, fop_contract_symbol, timedelta(days=3))
subset_history_open_interest_df = qb.History(OpenInterest, [fop_contract_symbol], timedelta(days=3))
all_history_open_interest_df = qb.History(OpenInterest, qb.Securities.Keys, timedelta(days=3))

# Slice objects
all_history_slice = qb.History(timedelta(days=3))

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](fop_contract_symbol, timedelta(days=3))
subset_history_trade_bars = qb.History[TradeBar]([fop_contract_symbol], timedelta(days=3))
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, timedelta(days=3))

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](fop_contract_symbol, timedelta(days=3), Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([fop_contract_symbol], timedelta(days=3), Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, timedelta(days=3), Resolution.Minute) 


# OpenInterest objects
single_history_open_interest = qb.History[OpenInterest](fop_contract_symbol, timedelta(days=2))
subset_history_open_interest = qb.History[OpenInterest]([fop_contract_symbol], timedelta(days=2))
all_history_open_interest = qb.History[OpenInterest](qb.Securities.Keys, timedelta(days=2))

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

Defined Period of Time

To get historical data for individual Futures Option contracts during a specific period of time, call the History method with the Futures Option contract Symbol object(s), a start DateTime datetime , and an end DateTime datetime . The start and end times you provide are based in the notebook time zone .

var startTime = new DateTime(2021, 12, 1);
var endTime = new DateTime(2021, 12, 31);

// Slice objects
var singleHistorySlice = qb.History(fopContractSymbol, startTime, endTime);
var subsetHistorySlice = qb.History(new[] {fopContractSymbol}, startTime, endTime);
var allHistorySlice = qb.History(startTime, endTime);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(fopContractSymbol, startTime, endTime);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {fopContractSymbol}, startTime, endTime);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, startTime, endTime);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(fopContractSymbol, startTime, endTime, Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {fopContractSymbol}, startTime, endTime, Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, startTime, endTime, Resolution.Minute);


// OpenInterest objects
var singleHistoryOpenInterest = qb.History<OpenInterest>(fopContractSymbol, startTime, endTime);
var subsetHistoryOpenInterest = qb.History<OpenInterest>(new[] {fopContractSymbol}, startTime, endTime);
var allHistoryOpenInterest = qb.History<OpenInterest>(qb.Securities.Keys, startTime, endTime);

start_time = datetime(2021, 12, 1)
end_time = datetime(2021, 12, 31)

# DataFrame of trade and quote data
single_history_df = qb.History(fop_contract_symbol, start_time, end_time)
subset_history_df = qb.History([fop_contract_symbol], start_time, end_time)
all_history_df = qb.History(qb.Securities.Keys, start_time, end_time)

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, fop_contract_symbol, start_time, end_time)
subset_history_trade_bar_df = qb.History(TradeBar, [fop_contract_symbol], start_time, end_time)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, start_time, end_time)

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, fop_contract_symbol, start_time, end_time)
subset_history_quote_bar_df = qb.History(QuoteBar, [fop_contract_symbol], start_time, end_time)
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, start_time, end_time)

# DataFrame of open interest data
single_history_open_interest_df = qb.History(OpenInterest, fop_contract_symbol, start_time, end_time)
subset_history_open_interest_df = qb.History(OpenInterest, [fop_contract_symbol], start_time, end_time)
all_history_trade_open_interest_df = qb.History(OpenInterest, qb.Securities.Keys, start_time, end_time)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](fop_contract_symbol, start_time, end_time)
subset_history_trade_bars = qb.History[TradeBar]([fop_contract_symbol], start_time, end_time)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, start_time, end_time)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](fop_contract_symbol, start_time, end_time, Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([fop_contract_symbol], start_time, end_time, Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, start_time, end_time, Resolution.Minute)


# OpenInterest objects
single_history_open_interest = qb.History[OpenInterest](fop_contract_symbol, start_time, end_time)
subset_history_open_interest = qb.History[OpenInterest]([fop_contract_symbol], start_time, end_time)
all_history_open_interest = qb.History[OpenInterest](qb.Securities.Keys, start_time, end_time)

To get historical data for all of the Futures Option contracts that traded during a specific period of time, call the GetOptionHistory method with the underlying Futures contract Symbol object, a start DateTime datetime , and an end DateTime datetime .

option_history = qb.GetOptionHistory(futures_contract_symbol, end_time-timedelta(days=2), end_time, Resolution.Minute, fillForward=False, extendedMarketHours=False)

var optionHistory = qb.GetOptionHistory(futuresContractSymbol, endTime-TimeSpan.FromDays(2), endTime, Resolution.Minute, fillForward: False, extendedMarketHours: False);

The preceding calls return data that have a timestamp within the defined period of time.

Resolutions

The following table shows the available resolutions and data formats for Future Option contract subscriptions:

Resolution	TradeBar	QuoteBar	Trade Tick	Quote Tick
Tick
Second
Minute
Hour
Daily

Markets

The following Market enumeration members are available for Future Options:

Wrangle Data

You need some historical data to perform wrangling operations. The process to manipulate the historical data depends on its data type. To display pandas objects, run a cell in a notebook with the pandas object as the last line. To display other data formats, call the print method.

You need some historical data to perform wrangling operations. Use LINQ to wrangle the data and then call the Console.WriteLine method in a Jupyter Notebook to display the data. The process to manipulate the historical data depends on its data type.

DataFrame Objects

If your history request returns a DataFrame , the DataFrame has the following index levels:

1. Contract expiry
2. Contract strike price
3. Contract type (call or put)
4. Encoded contract Symbol
5. The EndTime of the data sample

The columns of the DataFrame are the data properties. Depending on how you request data, the DataFrame may contain data for the underlying security, which causes some of the index levels to be an empty string for the corresponding rows.

To select the rows of the contract(s) that expire at a specific time, index the loc property of the DataFrame with the expiry time.

all_history_df.loc[datetime(2022, 3, 18)]

If you remove the first three index levels, you can index the DataFrame with just the contract Symbol , similiar to how you would with non-derivative asset classes. To remove the first three index levels, call the droplevel method.

all_history_df.index = all_history_df.index.droplevel([0,1,2])

To select the historical data of a single Futures Option contract, index the loc property of the DataFrame with the contract Symbol .

all_history_df.loc[fop_contract_symbol]

To select a column of the DataFrame , index it with the column name.

all_history_df.loc[fop_contract_symbol]['close']

If you request historical data for multiple Futures Option contracts, you can transform the DataFrame so that it's a time series of close values for all of the Futures Option contracts. To transform the DataFrame , select the column you want to display for each Futures Option contract and then call the unstack method.

all_history_df['close'].unstack(level=0)

The DataFrame is transformed so that the column indices are the Symbol of each security and each row contains the close value.

The historical data methods don't return DataFrame objects, but you can create one for efficient vectorized data wrangling.

using Microsoft.Data.Analysis; 

var columns = new DataFrameColumn[] {
    new PrimitiveDataFrameColumn("Time", history.Select(x => x[fopContractSymbol].EndTime)),
    new DecimalDataFrameColumn(" Open", history.Select(x => x[fopContractSymbol].Open)),
    new DecimalDataFrameColumn(" High", history.Select(x => x[fopContractSymbol].High)),
    new DecimalDataFrameColumn(" Low", history.Select(x => x[fopContractSymbol].Low)),
    new DecimalDataFrameColumn(" Close", history.Select(x => x[fopContractSymbol].Close))
};
var df = new DataFrame(columns);
df

To select a particular column of the DataFrame, index it with the column name.

df[" close"]

Slice Objects

If the History method returns Slice objects, iterate through the Slice objects to get each one. The Slice objects may not have data for all of your Futures Option subscriptions. To avoid issues, check if the Slice contains data for your Futures Option contract before you index it with the Futures Option Symbol .

foreach (var slice in allHistorySlice) {
    if (slice.Bars.ContainsKey(fopContractSymbol))
    {
        var tradeBar = slice.Bars[fopContractSymbol];
    }
    if (slice.QuoteBars.ContainsKey(fopContractSymbol))
    {
        var quoteBar = slice.QuoteBars[fopContractSymbol];
    }
}

for slice in all_history_slice:
        if slice.Bars.ContainsKey(fop_contract_symbol):
        trade_bar = slice.Bars[fop_contract_symbol]
    if slice.QuoteBars.ContainsKey(fop_contract_symbol):
        quote_bar = slice.QuoteBars[fop_contract_symbol]

You can also iterate through each TradeBar and QuoteBar in the Slice .

foreach (var slice in allHistorySlice)
{
    foreach (var kvp in slice.Bars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
    foreach (var kvp in slice.QuoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for slice in all_history_slice:
    for kvp in slice.Bars:
        symbol = kvp.Key
        trade_bar = kvp.Value
    for kvp in slice.QuoteBars:
        symbol = kvp.Key
        quote_bar = kvp.Value

You can also use LINQ to select each TradeBar in the Slice for a given Symbol .

var tradeBars = allHistorySlice.Where(slice => slice.Bars.ContainsKey(fopContractSymbol)).Select(slice => slice.Bars[fopContractSymbol]);

TradeBar Objects

If the History method returns TradeBar objects, iterate through the TradeBar objects to get each one.

foreach (var tradeBar in singleHistoryTradeBars)
{
    Console.WriteLine(tradeBar);
}

for trade_bar in single_history_trade_bars:
    print(trade_bar)

If the History method returns TradeBars , iterate through the TradeBars to get the TradeBar of each Futures Option contract. The TradeBars may not have data for all of your Futures Option subscriptions. To avoid issues, check if the TradeBars object contains data for your security before you index it with the Futures Option Symbol .

foreach (var tradeBars in allHistoryTradeBars)
{
    if (tradeBars.ContainsKey(fopContractSymbol))
    {
        var tradeBar = tradeBars[fopContractSymbol];
    }
}

for trade_bars in all_history_trade_bars:
    if trade_bars.ContainsKey(fop_contract_symbol):
        trade_bar = trade_bars[fop_contract_symbol]

You can also iterate through each of the TradeBars .

foreach (var tradeBars in allHistoryTradeBars)
{
    foreach (var kvp in tradeBars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
}

for trade_bars in all_history_trade_bars:
    for kvp in trade_bars:
        symbol = kvp.Key
        trade_bar = kvp.Value

QuoteBar Objects

If the History method returns QuoteBar objects, iterate through the QuoteBar objects to get each one.

foreach (var quoteBar in singleHistoryQuoteBars)
{
    Console.WriteLine(quoteBar);
}

for quote_bar in single_history_quote_bars:
    print(quote_bar)

If the History method returns QuoteBars , iterate through the QuoteBars to get the QuoteBar of each Futures Option contract. The QuoteBars may not have data for all of your Futures Option subscriptions. To avoid issues, check if the QuoteBars object contains data for your security before you index it with the Futures Option Symbol .

foreach (var quoteBars in allHistoryQuoteBars)
{
    if (quoteBars.ContainsKey(fopContractSymbol))
    {
        var quoteBar = quoteBars[fopContractSymbol];
    }
}

for quote_bars in all_history_quote_bars:
    if quote_bars.ContainsKey(fop_contract_symbol):
        quote_bar = quote_bars[fop_contract_symbol]

You can also iterate through each of the QuoteBars .

foreach (var quoteBars in allHistoryQuoteBars)
{
    foreach (var kvp in quoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for quote_bars in all_history_quote_bars:
    for kvp in quote_bars:
        symbol = kvp.Key
        quote_bar = kvp.Value

OpenInterest Objects

If the History method returns OpenInterest objects, iterate through the OpenInterest objects to get each one.

foreach (var openInterest in singleHistoryOpenInterest)
{
    Console.WriteLine(openInterest);
}

for open_interest in single_history_open_interest:
    print(open_interest)

If the History method returns a dictionary of OpenInterest objects, iterate through the dictionary to get the OpenInterest of each Futures Option contract. The dictionary of OpenInterest objects may not have data for all of your Futures Option contract subscriptions. To avoid issues, check if the dictionary contains data for your contract before you index it with the Futures Option contract Symbol .

foreach (var openInterestDict in allHistoryOpenInterest)
{
    if (openInterestDict.ContainsKey(fopContractSymbol))
    {
        var openInterest = openInterestDict[fopContractSymbol];
    }
}

for open_interest_dict in all_history_open_interest:
    if open_interest_dict.ContainsKey(fop_contract_symbol):
        open_interest = open_interest_dict[fop_contract_symbol]

You can also iterate through each of the OpenInterest dictionaries.

foreach (var openInterestDict in allHistoryOpenInterest)
{
    foreach (var kvp in openInterestDict)
    {
        var symbol = kvp.Key;
        var openInterest = kvp.Value;
    }
}

for open_interest_dict in all_history_open_interest:
    for kvp in open_interest_dict:
        symbol = kvp.Key
        open_interest = kvp.Value

OptionHistory Objects

The GetOptionHistory method returns an OptionHistory object. To get each slice in the OptionHistory object, iterate through it.

foreach (var slice in optionHistory)
{
    foreach (var kvp in slice.OptionChains)
    {
        var canonicalSymbol = kvp.Key;
        var chain = kvp.Value;
        foreach (var contract in chain)
        {
            
        }
    }
}

for slice in option_history:
    for canonical_symbol, chain in slice.OptionChains.items(): 
        for contract in chain:
            pass

To convert the OptionHistory object to a DataFrame that contains the trade and quote information of each contract and the underlying, call the GetAllData method.

option_history.GetAllData()

To get the expiration dates of all the contracts in an OptionHistory object, call the GetExpiryDates method.

option_history.GetExpiryDates()

To get the strike prices of all the contracts in an OptionHistory object, call the GetStrikes method.

option_history.GetStrikes()

Plot Data

Jupyter Notebooks don't currently support libraries to plot historical data, but we are working on adding the functionality. Until we add the functionality, use Python to plot historical Future Options data.

You need to get some historical Future Options data to plot it. You can use many of the supported plotting libraries to visualize data in various formats. For example, you can plot candlestick and line charts.

Candlestick Chart

Follow these steps to plot candlestick charts:

1. Get some historical data.

history = qb.History(fop_contract_symbol, datetime(2021, 12, 2), datetime(2021, 12, 3))

var history = qb.History<QuoteBar>(fopContractSymbol, new DateTime(2021, 12, 2), new DateTime(2021, 12, 3));

2. Drop the first four index levels of the DataFrame that returns.

history.index = history.index.droplevel([0,1,2,3])

3. Import the plotly Plotly.NET library.

import plotly.graph_objects as go

#r "../Plotly.NET.dll"
using Plotly.NET;
using Plotly.NET.LayoutObjects;

4. Create a Candlestick .
   

candlestick = go.Candlestick(x=history.index,
                             open=history['open'],
                             high=history['high'],
                             low=history['low'],
                             close=history['close'])

var chart = Chart2D.Chart.Candlestick<decimal, decimal, decimal, decimal, DateTime, string>(
    history.Select(x => x.Open),
    history.Select(x => x.High),
    history.Select(x => x.Low),
    history.Select(x => x.Close),
    history.Select(x => x.EndTime)
);

5. Create a Layout .
   

layout = go.Layout(title=go.layout.Title(text=f'{fop_contract_symbol.Value} OHLC'),
                   xaxis_title='Date',
                   yaxis_title='Price',
                   xaxis_rangeslider_visible=False)

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{fopContractSymbol} OHLC");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

6. Create the Figure .
   

fig = go.Figure(data=[candlestick], layout=layout)

7. Assign the Layout to the chart.
   

chart.WithLayout(layout);

8. Show the Figure .
   

fig.show()

HTML(GenericChart.toChartHTML(chart))

Candlestick charts display the open, high, low, and close prices of the contract.

Line Chart

Follow these steps to plot line charts using built-in methods Plotly.NET package :

1. Get some historical data.

history = qb.History(fop_contract_symbols[:5], datetime(2021, 12, 2), datetime(2021, 12, 30), Resolution.Daily)

2. Drop the first three index levels of the returned pandas.DataFrame .

history.index = history.index.droplevel([0,1,2])

3. Select the data to plot.

closes = history['close'].unstack(level=0)

4. Call the plot method on the pandas object.

closes.plot(title="Close", figsize=(15, 5))

5. Create Line charts.

var chart = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x.EndTime),
    history.Select(x => x.Close)
);

6. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{fopContractSymbol} Close");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

7. Assign the Layout to the chart.
   

chart.WithLayout(layout);

8. Show the plot.

plt.show()

HTML(GenericChart.toChartHTML(chart))

Line charts display the value of the property you selected in a time series.

Datasets > Forex

Introduction

This page explains how to request, manipulate, and visualize historical Forex data.

Create Subscriptions

Follow these steps to subscribe to a Forex security:

1. Load the required assembly files and data types.

#load "../Initialize.csx"
#load "../QuantConnect.csx"
#r "../Microsoft.Data.Analysis.dll"

using QuantConnect;
using QuantConnect.Data;
using QuantConnect.Algorithm;
using QuantConnect.Research;
using Microsoft.Data.Analysis;

2. Create a QuantBook .

var qb = new QuantBook();

qb = QuantBook()

3. Call the AddForex method with a ticker and then save a reference to the Forex Symbol .

var eurusd = qb.AddForex("EURUSD").Symbol;
var gbpusd = qb.AddForex("GBPUSD").Symbol;

eurusd = qb.AddForex("EURUSD").Symbol
gbpusd = qb.AddForex("GBPUSD").Symbol

To view all of the available Forex pairs, see Supported Assets .

Get Historical Data

You need a subscription before you can request historical data for a security. On the time dimension, you can request an amount of historical data based on a trailing number of bars, a trailing period of time, or a defined period of time. On the security dimension, you can request historical data for a single Forex pair, a subset of the pairs you created subscriptions for in your notebook, or all of the pairs in your notebook.

Trailing Number of Bars

To get historical data for a number of trailing bars, call the History method with the Symbol object(s) and an integer.

// Slice objects
var singleHistorySlice = qb.History(eurusd, 10);
var subsetHistorySlice = qb.History(new[] {eurusd, gbpusd}, 10);
var allHistorySlice = qb.History(10);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(eurusd, 10);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {eurusd, gbpusd}, 10);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, 10);

# DataFrame
single_history_df = qb.History(eurusd, 10)
subset_history_df = qb.History([eurusd, gbpusd], 10)
all_history_df = qb.History(qb.Securities.Keys, 10)

# Slice objects
all_history_slice = qb.History(10)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](eurusd, 10)
subset_history_quote_bars = qb.History[QuoteBar]([eurusd, gbpusd], 10)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, 10)

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

Trailing Period of Time

To get historical data for a trailing period of time, call the History method with the Symbol object(s) and a TimeSpan timedelta .

// Slice objects
var singleHistorySlice = qb.History(eurusd, TimeSpan.FromDays(3));
var subsetHistorySlice = qb.History(new[] {eurusd, gbpusd}, TimeSpan.FromDays(3));
var allHistorySlice = qb.History(10);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(eurusd, TimeSpan.FromDays(3), Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {eurusd, gbpusd}, TimeSpan.FromDays(3), Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Minute);

// Tick objects
var singleHistoryTicks = qb.History<Tick>(eurusd, TimeSpan.FromDays(3), Resolution.Tick);
var subsetHistoryTicks = qb.History<Tick>(new[] {eurusd, gbpusd}, TimeSpan.FromDays(3), Resolution.Tick);
var allHistoryTicks = qb.History<Tick>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Tick);

# DataFrame of quote data (Forex data doesn't have trade data)
single_history_df = qb.History(eurusd, timedelta(days=3))
subset_history_df = qb.History([eurusd, gbpusd], timedelta(days=3))
all_history_df = qb.History(qb.Securities.Keys, timedelta(days=3))

# DataFrame of tick data
single_history_tick_df = qb.History(eurusd, timedelta(days=3), Resolution.Tick)
subset_history_tick_df = qb.History([eurusd, gbpusd], timedelta(days=3), Resolution.Tick)
all_history_tick_df = qb.History(qb.Securities.Keys, timedelta(days=3), Resolution.Tick)

# Slice objects
all_history_slice = qb.History(timedelta(days=3))

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](eurusd, timedelta(days=3), Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([eurusd, gbpusd], timedelta(days=3), Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, timedelta(days=3), Resolution.Minute)

# Tick objects
single_history_ticks = qb.History[Tick](eurusd, timedelta(days=3), Resolution.Tick)
subset_history_ticks = qb.History[Tick]([eurusd, gbpusd], timedelta(days=3), Resolution.Tick)
all_history_ticks = qb.History[Tick](qb.Securities.Keys, timedelta(days=3), Resolution.Tick)

The preceding calls return the most recent bars or ticks, excluding periods of time when the exchange was closed.

Defined Period of Time

To get historical data for a specific period of time, call the History method with the Symbol object(s), a start DateTime datetime , and an end DateTime datetime . The start and end times you provide are based in the notebook time zone .

var startTime = new DateTime(2021, 1, 1);
var endTime = new DateTime(2021, 2, 1);

// Slice objects
var singleHistorySlice = qb.History(eurusd, startTime, endTime);
var subsetHistorySlice = qb.History(new[] {eurusd, gbpusd}, startTime, endTime);
var allHistorySlice = qb.History(qb.Securities.Keys, startTime, endTime);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(eurusd, startTime, endTime, Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {eurusd, gbpusd}, startTime, endTime, Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, startTime, endTime, Resolution.Minute);

// Tick objects
var singleHistoryTicks = qb.History<Tick>(eurusd, startTime, endTime, Resolution.Tick);
var subsetHistoryTicks = qb.History<Tick>(new[] {eurusd, gbpusd}, startTime, endTime, Resolution.Tick);
var allHistoryTicks = qb.History<Tick>(qb.Securities.Keys, startTime, endTime, Resolution.Tick);

start_time = datetime(2021, 1, 1)
end_time = datetime(2021, 2, 1)

# DataFrame of quote data (Forex data doesn't have trade data)
single_history_df = qb.History(eurusd, start_time, end_time)
subset_history_df = qb.History([eurusd, gbpusd], start_time, end_time)
all_history_df = qb.History(qb.Securities.Keys, start_time, end_time)

# DataFrame of tick data
single_history_tick_df = qb.History(eurusd, start_time, end_time, Resolution.Tick)
subset_history_tick_df = qb.History([eurusd, gbpusd], start_time, end_time, Resolution.Tick)
all_history_tick_df = qb.History(qb.Securities.Keys, start_time, end_time, Resolution.Tick)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](eurusd, start_time, end_time, Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([eurusd, gbpusd], start_time, end_time, Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, start_time, end_time, Resolution.Minute)

# Tick objects
single_history_ticks = qb.History[Tick](eurusd, start_time, end_time, Resolution.Tick)
subset_history_ticks = qb.History[Tick]([eurusd, gbpusd], start_time, end_time, Resolution.Tick)
all_history_ticks = qb.History[Tick](qb.Securities.Keys, start_time, end_time, Resolution.Tick)

The preceding calls return the bars or ticks that have a timestamp within the defined period of time.

Resolutions

The following table shows the available resolutions and data formats for Forex subscriptions:

Resolution	TradeBar	QuoteBar	Trade Tick	Quote Tick
Tick
Second
Minute
Hour
Daily

Markets

The only market available for Forex pairs is Market.Oanda .

Wrangle Data

You need some historical data to perform wrangling operations. The process to manipulate the historical data depends on its data type. To display pandas objects, run a cell in a notebook with the pandas object as the last line. To display other data formats, call the print method.

You need some historical data to perform wrangling operations. Use LINQ to wrangle the data and then call the Console.WriteLine method in a Jupyter Notebook to display the data. The process to manipulate the historical data depends on its data type.

DataFrame Objects

If the History method returns a DataFrame , the first level of the DataFrame index is the encoded Forex Symbol and the second level is the EndTime of the data sample. The columns of the DataFrame are the data properties.

To select the historical data of a single Forex, index the loc property of the DataFrame with the Forex Symbol .

all_history_df.loc[eurusd]  # or all_history_df.loc['EURUSD']

To select a column of the DataFrame , index it with the column name.

all_history_df.loc[eurusd]['close']

If you request historical data for multiple Forex pairs, you can transform the DataFrame so that it's a time series of close values for all of the Forex pairs. To transform the DataFrame , select the column you want to display for each Forex pair and then call the unstack method.

all_history_df['close'].unstack(level=0)

The DataFrame is transformed so that the column indices are the Symbol of each Forex pair and each row contains the close value.

The historical data methods don't return DataFrame objects, but you can create one for efficient vectorized data wrangling.

using Microsoft.Data.Analysis; 

var columns = new DataFrameColumn[] {
    new PrimitiveDataFrameColumn("Time", history.Select(x => x[eurusd].EndTime)),
    new DecimalDataFrameColumn("EURUSD Open", history.Select(x => x[eurusd].Open)),
    new DecimalDataFrameColumn("EURUSD High", history.Select(x => x[eurusd].High)),
    new DecimalDataFrameColumn("EURUSD Low", history.Select(x => x[eurusd].Low)),
    new DecimalDataFrameColumn("EURUSD Close", history.Select(x => x[eurusd].Close))
};
var df = new DataFrame(columns);
df

To select a particular column of the DataFrame, index it with the column name.

df["EURUSD close"]

Slice Objects

If the History method returns Slice objects, iterate through the Slice objects to get each one. The Slice objects may not have data for all of your Forex subscriptions. To avoid issues, check if the Slice contains data for your Forex pair before you index it with the Forex Symbol .

foreach (var slice in allHistorySlice) {
    if (slice.QuoteBars.ContainsKey(eurusd))
    {
        var quoteBar = slice.QuoteBars[eurusd];
    }
}

for slice in all_history_slice:
        if slice.QuoteBars.ContainsKey(eurusd):
        quote_bar = slice.QuoteBars[eurusd]

You can also iterate through each QuoteBar in the Slice .

foreach (var slice in allHistorySlice)
{
    foreach (var kvp in slice.QuoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for slice in all_history_slice:
    for kvp in slice.QuoteBars:
        symbol = kvp.Key
        quote_bar = kvp.Value

You can also use LINQ to select each QuoteBar in the Slice for a given Symbol .

var quoteBars = allHistorySlice.Where(slice => slice.QuoteBars.ContainsKey(eurusd)).Select(slice => slice.QuoteBars[eurusd]);

QuoteBar Objects

If the History method returns QuoteBar objects, iterate through the QuoteBar objects to get each one.

foreach (var quoteBar in singleHistoryQuoteBars)
{
    Console.WriteLine(quoteBar);
}

for quote_bar in single_history_quote_bars:
    print(quote_bar)

If the History method returns QuoteBars , iterate through the QuoteBars to get the QuoteBar of each Forex pair. The QuoteBars may not have data for all of your Forex subscriptions. To avoid issues, check if the QuoteBars object contains data for your security before you index it with the Forex Symbol .

foreach (var quoteBars in allHistoryQuoteBars)
{
    if (quoteBars.ContainsKey(eurusd))
    {
        var quoteBar = quoteBars[eurusd];
    }
}

for quote_bars in all_history_quote_bars:
    if quote_bars.ContainsKey(eurusd):
        quote_bar = quote_bars[eurusd]

You can also iterate through each of the QuoteBars .

foreach (var quoteBars in allHistoryQuoteBars)
{
    foreach (var kvp in quoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for quote_bars in all_history_quote_bars:
    for kvp in quote_bars:
        symbol = kvp.Key
        quote_bar = kvp.Value

Tick Objects

If the History method returns Tick objects, iterate through the Tick objects to get each one.

foreach (var tick in singleHistoryTicks)
{
    Console.WriteLine(tick);
}

for tick in single_history_ticks:
    print(tick)

If the History method returns Ticks , iterate through the Ticks to get the Tick of each Forex pair. The Ticks may not have data for all of your Forex subscriptions. To avoid issues, check if the Ticks object contains data for your security before you index it with the Forex Symbol .

foreach (var ticks in allHistoryTicks)
{
    if (ticks.ContainsKey(eurusd))
    {
        var tick = ticks[eurusd];
    }
}

for ticks in all_history_ticks:
    if ticks.ContainsKey(eurusd):
        ticks = ticks[eurusd]

You can also iterate through each of the Ticks .

foreach (var ticks in allHistoryTicks)
{
    foreach (var kvp in ticks)
    {
        var symbol = kvp.Key;
        var tick = kvp.Value;
    }
}

for ticks in all_history_ticks:
    for kvp in ticks:
        symbol = kvp.Key
        tick = kvp.Value

Plot Data

You need some historical Forex data to produce plots. You can use many of the supported plotting libraries Plot.NET package to visualize data in various formats. For example, you can plot candlestick and line charts.

Candlestick Chart

Follow these steps to plot candlestick charts:

1. Get some historical data.

history = qb.History(eurusd, datetime(2021, 11, 26), datetime(2021, 12, 8), Resolution.Daily).loc[eurusd]

var history = qb.History<QuoteBar>(eurusd, new DateTime(2021, 11, 26), new DateTime(2021, 12, 8), Resolution.Daily);

2. Import the plotly Plotly.NET library.

import plotly.graph_objects as go

#r "../Plotly.NET.dll"
using Plotly.NET;
using Plotly.NET.LayoutObjects;

3. Create a Candlestick .
   

candlestick = go.Candlestick(x=history.index,
                             open=history['open'],
                             high=history['high'],
                             low=history['low'],
                             close=history['close'])

var chart = Chart2D.Chart.Candlestick<decimal, decimal, decimal, decimal, DateTime, string>(
    history.Select(x => x.Open),
    history.Select(x => x.High),
    history.Select(x => x.Low),
    history.Select(x => x.Close),
    history.Select(x => x.EndTime)
);

4. Create a Layout .
   

layout = go.Layout(title=go.layout.Title(text='EURUSD OHLC'),
                   xaxis_title='Date',
                   yaxis_title='Price',
                   xaxis_rangeslider_visible=False)

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{eurusd} OHLC");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

5. Create the Figure .
   

fig = go.Figure(data=[candlestick], layout=layout)

6. Assign the Layout to the chart.
   

chart.WithLayout(layout);

7. Show the Figure .
   

fig.show()

HTML(GenericChart.toChartHTML(chart))

Candlestick charts display the open, high, low, and close prices of the security.

Line Chart

Follow these steps to plot line charts using built-in methods Plotly.NET package :

1. Get some historical data.

history = qb.History([eurusd, gbpusd], datetime(2021, 11, 26), datetime(2021, 12, 8), Resolution.Daily)

var history = qb.History<QuoteBar>(new [] {eurusd, gbpusd}, new DateTime(2021, 11, 26), new DateTime(2021, 12, 8), Resolution.Daily);

2. Select the data to plot.

pct_change = history['close'].unstack(0).pct_change().dropna()

3. Call the plot method on the pandas object.

pct_change.plot(title="Close Price %Change", figsize=(15, 10))

4. Create Line charts.

var chart1 = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x[eurusd].EndTime),
    history.Select(x => x[eurusd].Close),
    Name: "EURUSD"
);
var chart2 = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x[gbpusd].EndTime),
    history.Select(x => x[gbpusd].Close),
    Name: "GBPUSD"
);

5. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init("EURUSD & GBPUSD Close Price");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

6. Combine the charts and assign the Layout to the chart.
   

var chart = Plotly.NET.Chart.Combine(new []{chart1, chart2});
chart.WithLayout(layout);

7. Show the plot.

plt.show()

HTML(GenericChart.toChartHTML(chart))

Line charts display the value of the property you selected in a time series.

Datasets > CFD

Introduction

This page explains how to request, manipulate, and visualize historical CFD data.

Create Subscriptions

Follow these steps to subscribe to a CFD security:

1. Load the required assembly files and data types.

#load "../Initialize.csx"
#load "../QuantConnect.csx"
#r "../Microsoft.Data.Analysis.dll"

using QuantConnect;
using QuantConnect.Data;
using QuantConnect.Algorithm;
using QuantConnect.Research;
using Microsoft.Data.Analysis;

2. Create a QuantBook .

var qb = new QuantBook();

qb = QuantBook()

3. Call the AddCfd method with a ticker and then save a reference to the CFD Symbol .

var spx = qb.AddCfd("SPX500USD").Symbol;
var usb = qb.AddCfd("USB10YUSD").Symbol;

spx = qb.AddCfd("SPX500USD").Symbol
usb = qb.AddCfd("USB10YUSD").Symbol

To view all of the available contracts, see Supported Assets .

Get Historical Data

You need a subscription before you can request historical data for a security. On the time dimension, you can request an amount of historical data based on a trailing number of bars, a trailing period of time, or a defined period of time. On the security dimension, you can request historical data for a single CFD contract, a subset of the contracts you created subscriptions for in your notebook, or all of the contracts in your notebook.

Trailing Number of Bars

To get historical data for a number of trailing bars, call the History method with the Symbol object(s) and an integer.

// Slice objects
var singleHistorySlice = qb.History(spx, 10);
var subsetHistorySlice = qb.History(new[] {spx, usb}, 10);
var allHistorySlice = qb.History(10);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(spx, 10);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {spx, usb}, 10);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, 10);

# DataFrame
single_history_df = qb.History(spx, 10)
subset_history_df = qb.History([spx, usb], 10)
all_history_df = qb.History(qb.Securities.Keys, 10)

# Slice objects
all_history_slice = qb.History(10)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](spx, 10)
subset_history_quote_bars = qb.History[QuoteBar]([spx, usb], 10)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, 10)

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

Trailing Period of Time

To get historical data for a trailing period of time, call the History method with the Symbol object(s) and a TimeSpan timedelta .

// Slice objects
var singleHistorySlice = qb.History(spx, TimeSpan.FromDays(3));
var subsetHistorySlice = qb.History(new[] {spx, usb}, TimeSpan.FromDays(3));
var allHistorySlice = qb.History(10);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(spx, TimeSpan.FromDays(3), Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {spx, usb}, TimeSpan.FromDays(3), Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Minute);

// Tick objects
var singleHistoryTicks = qb.History<Tick>(spx, TimeSpan.FromDays(3), Resolution.Tick);
var subsetHistoryTicks = qb.History<Tick>(new[] {spx, usb}, TimeSpan.FromDays(3), Resolution.Tick);
var allHistoryTicks = qb.History<Tick>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Tick);

# DataFrame of quote data (CFD data doesn't have trade data)
single_history_df = qb.History(spx, timedelta(days=3))
subset_history_df = qb.History([spx, usb], timedelta(days=3))
all_history_df = qb.History(qb.Securities.Keys, timedelta(days=3))

# DataFrame of tick data
single_history_tick_df = qb.History(spx, timedelta(days=3), Resolution.Tick)
subset_history_tick_df = qb.History([spx, usb], timedelta(days=3), Resolution.Tick)
all_history_tick_df = qb.History(qb.Securities.Keys, timedelta(days=3), Resolution.Tick)

# Slice objects
all_history_slice = qb.History(timedelta(days=3))

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](spx, timedelta(days=3), Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([spx, usb], timedelta(days=3), Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, timedelta(days=3), Resolution.Minute)

# Tick objects
single_history_ticks = qb.History[Tick](spx, timedelta(days=3), Resolution.Tick)
subset_history_ticks = qb.History[Tick]([spx, usb], timedelta(days=3), Resolution.Tick)
all_history_ticks = qb.History[Tick](qb.Securities.Keys, timedelta(days=3), Resolution.Tick)

The preceding calls return the most recent bars or ticks, excluding periods of time when the exchange was closed.

Defined Period of Time

To get historical data for a specific period of time, call the History method with the Symbol object(s), a start DateTime datetime , and an end DateTime datetime . The start and end times you provide are based in the notebook time zone .

var startTime = new DateTime(2021, 1, 1);
var endTime = new DateTime(2021, 2, 1);

// Slice objects
var singleHistorySlice = qb.History(spx, startTime, endTime);
var subsetHistorySlice = qb.History(new[] {spx, usb}, startTime, endTime);
var allHistorySlice = qb.History(qb.Securities.Keys, startTime, endTime);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>(spx, startTime, endTime, Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {spx, usb}, startTime, endTime, Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, startTime, endTime, Resolution.Minute);

// Tick objects
var singleHistoryTicks = qb.History<Tick>(spx, startTime, endTime, Resolution.Tick);
var subsetHistoryTicks = qb.History<Tick>(new[] {spx, usb}, startTime, endTime, Resolution.Tick);
var allHistoryTicks = qb.History<Tick>(qb.Securities.Keys, startTime, endTime, Resolution.Tick);

start_time = datetime(2021, 1, 1)
end_time = datetime(2021, 2, 1)

# DataFrame of quote data (CFD data doesn't have trade data)
single_history_df = qb.History(spx, start_time, end_time)
subset_history_df = qb.History([spx, usb], start_time, end_time)
all_history_df = qb.History(qb.Securities.Keys, start_time, end_time)

# DataFrame of tick data
single_history_tick_df = qb.History(spx, start_time, end_time, Resolution.Tick)
subset_history_tick_df = qb.History([spx, usb], start_time, end_time, Resolution.Tick)
all_history_tick_df = qb.History(qb.Securities.Keys, start_time, end_time, Resolution.Tick)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar](spx, start_time, end_time, Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar]([spx, usb], start_time, end_time, Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, start_time, end_time, Resolution.Minute)

# Tick objects
single_history_ticks = qb.History[Tick](spx, start_time, end_time, Resolution.Tick)
subset_history_ticks = qb.History[Tick]([spx, usb], start_time, end_time, Resolution.Tick)
all_history_ticks = qb.History[Tick](qb.Securities.Keys, start_time, end_time, Resolution.Tick)

The preceding calls return the bars or ticks that have a timestamp within the defined period of time.

Resolutions

The following table shows the available resolutions and data formats for CFD subscriptions:

Resolution	TradeBar	QuoteBar	Trade Tick	Quote Tick
Tick
Second
Minute
Hour
Daily

Markets

The only market available for CFD contracts is Market.Oanda .

Wrangle Data

You need some historical data to perform wrangling operations. The process to manipulate the historical data depends on its data type. To display pandas objects, run a cell in a notebook with the pandas object as the last line. To display other data formats, call the print method.

You need some historical data to perform wrangling operations. Use LINQ to wrangle the data and then call the Console.WriteLine method in a Jupyter Notebook to display the data. The process to manipulate the historical data depends on its data type.

DataFrame Objects

If the History method returns a DataFrame , the first level of the DataFrame index is the encoded CFD Symbol and the second level is the EndTime of the data sample. The columns of the DataFrame are the data properties.

To select the historical data of a single CFD, index the loc property of the DataFrame with the CFD Symbol .

all_history_df.loc[spx]  # or all_history_df.loc['SPX500USD']

To select a column of the DataFrame , index it with the column name.

all_history_df.loc[spx]['close']

If you request historical data for multiple CFD contracts, you can transform the DataFrame so that it's a time series of close values for all of the CFD contracts. To transform the DataFrame , select the column you want to display for each CFD contract and then call the unstack method.

all_history_df['close'].unstack(level=0)

The DataFrame is transformed so that the column indices are the Symbol of each CFD contract and each row contains the close value.

The historical data methods don't return DataFrame objects, but you can create one for efficient vectorized data wrangling.

using Microsoft.Data.Analysis; 

var columns = new DataFrameColumn[] {
    new PrimitiveDataFrameColumn("Time", history.Select(x => x[spx].EndTime)),
    new DecimalDataFrameColumn("SPX500USD Open", history.Select(x => x[spx].Open)),
    new DecimalDataFrameColumn("SPX500USD High", history.Select(x => x[spx].High)),
    new DecimalDataFrameColumn("SPX500USD Low", history.Select(x => x[spx].Low)),
    new DecimalDataFrameColumn("SPX500USD Close", history.Select(x => x[spx].Close))
};
var df = new DataFrame(columns);
df

To select a particular column of the DataFrame, index it with the column name.

df["SPX500USD close"]

Slice Objects

If the History method returns Slice objects, iterate through the Slice objects to get each one. The Slice objects may not have data for all of your CFD subscriptions. To avoid issues, check if the Slice contains data for your CFD contract before you index it with the CFD Symbol .

foreach (var slice in allHistorySlice) {
    if (slice.QuoteBars.ContainsKey(spx))
    {
        var quoteBar = slice.QuoteBars[spx];
    }
}

for slice in all_history_slice:
        if slice.QuoteBars.ContainsKey(spx):
        quote_bar = slice.QuoteBars[spx]

You can also iterate through each QuoteBar in the Slice .

foreach (var slice in allHistorySlice)
{
    foreach (var kvp in slice.QuoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for slice in all_history_slice:
    for kvp in slice.QuoteBars:
        symbol = kvp.Key
        quote_bar = kvp.Value

You can also use LINQ to select each QuoteBar in the Slice for a given Symbol .

var quoteBars = allHistorySlice.Where(slice => slice.QuoteBars.ContainsKey(spx)).Select(slice => slice.QuoteBars[spx]);

QuoteBar Objects

If the History method returns QuoteBar objects, iterate through the QuoteBar objects to get each one.

foreach (var quoteBar in singleHistoryQuoteBars)
{
    Console.WriteLine(quoteBar);
}

for quote_bar in single_history_quote_bars:
    print(quote_bar)

If the History method returns QuoteBars , iterate through the QuoteBars to get the QuoteBar of each CFD contract. The QuoteBars may not have data for all of your CFD subscriptions. To avoid issues, check if the QuoteBars object contains data for your security before you index it with the CFD Symbol .

foreach (var quoteBars in allHistoryQuoteBars)
{
    if (quoteBars.ContainsKey(spx))
    {
        var quoteBar = quoteBars[spx];
    }
}

for quote_bars in all_history_quote_bars:
    if quote_bars.ContainsKey(spx):
        quote_bar = quote_bars[spx]

You can also iterate through each of the QuoteBars .

foreach (var quoteBars in allHistoryQuoteBars)
{
    foreach (var kvp in quoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for quote_bars in all_history_quote_bars:
    for kvp in quote_bars:
        symbol = kvp.Key
        quote_bar = kvp.Value

Tick Objects

If the History method returns Tick objects, iterate through the Tick objects to get each one.

foreach (var tick in singleHistoryTicks)
{
    Console.WriteLine(tick);
}

for tick in single_history_ticks:
    print(tick)

If the History method returns Ticks , iterate through the Ticks to get the Tick of each CFD contract. The Ticks may not have data for all of your CFD subscriptions. To avoid issues, check if the Ticks object contains data for your security before you index it with the CFD Symbol .

foreach (var ticks in allHistoryTicks)
{
    if (ticks.ContainsKey(spx))
    {
        var tick = ticks[spx];
    }
}

for ticks in all_history_ticks:
    if ticks.ContainsKey(spx):
        ticks = ticks[spx]

You can also iterate through each of the Ticks .

foreach (var ticks in allHistoryTicks)
{
    foreach (var kvp in ticks)
    {
        var symbol = kvp.Key;
        var tick = kvp.Value;
    }
}

for ticks in all_history_ticks:
    for kvp in ticks:
        symbol = kvp.Key
        tick = kvp.Value

Plot Data

You need some historical CFD data to produce plots. You can use many of the supported plotting libraries Plot.NET package to visualize data in various formats. For example, you can plot candlestick and line charts.

Candlestick Chart

Follow these steps to plot candlestick charts:

1. Get some historical data.

history = qb.History(spx, datetime(2021, 11, 26), datetime(2021, 12, 8), Resolution.Daily).loc[spx]

var history = qb.History<QuoteBar>(spx, new DateTime(2021, 11, 26), new DateTime(2021, 12, 8), Resolution.Daily);

2. Import the plotly Plotly.NET library.

import plotly.graph_objects as go

#r "../Plotly.NET.dll"
using Plotly.NET;
using Plotly.NET.LayoutObjects;

3. Create a Candlestick .
   

candlestick = go.Candlestick(x=history.index,
                             open=history['open'],
                             high=history['high'],
                             low=history['low'],
                             close=history['close'])

var chart = Chart2D.Chart.Candlestick<decimal, decimal, decimal, decimal, DateTime, string>(
    history.Select(x => x.Open),
    history.Select(x => x.High),
    history.Select(x => x.Low),
    history.Select(x => x.Close),
    history.Select(x => x.EndTime)
);

4. Create a Layout .
   

layout = go.Layout(title=go.layout.Title(text='SPX CFD OHLC'),
                   xaxis_title='Date',
                   yaxis_title='Price',
                   xaxis_rangeslider_visible=False)

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{spx} OHLC");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

5. Create the Figure .
   

fig = go.Figure(data=[candlestick], layout=layout)

6. Assign the Layout to the chart.
   

chart.WithLayout(layout);

7. Show the Figure .
   

fig.show()

HTML(GenericChart.toChartHTML(chart))

Candlestick charts display the open, high, low, and close prices of the security.

Line Chart

Follow these steps to plot line charts using built-in methods Plotly.NET package :

1. Get some historical data.

history = qb.History([spx, usb], datetime(2021, 11, 26), datetime(2021, 12, 8), Resolution.Daily)

var history = qb.History<QuoteBar>(new [] {spx, usb}, new DateTime(2021, 11, 26), new DateTime(2021, 12, 8), Resolution.Daily);

2. Select the data to plot.

pct_change = history['close'].unstack(0).pct_change().dropna()

3. Call the plot method on the pandas object.

pct_change.plot(title="Close Price %Change", figsize=(15, 10))

4. Create Line charts.

var chart1 = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x[spx].EndTime),
    history.Select(x => x[spx].Close - x[spx].Open),
    Name: $"{spx}"
);
var chart2 = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x[usb].EndTime),
    history.Select(x => x[usb].Close - x[usb].Open),
    Name: $"{usb}"
);

5. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{spx} & {usb} Daily Spread");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

6. Combine the charts and assign the Layout to the chart.
   

var chart = Plotly.NET.Chart.Combine(new []{chart1, chart2});
chart.WithLayout(layout);

7. Show the plot.

plt.show()

HTML(GenericChart.toChartHTML(chart))

Line charts display the value of the property you selected in a time series.

Datasets > Indices

Introduction

This page explains how to request, manipulate, and visualize historical Index data.

Create Subscriptions

Follow these steps to subscribe to an Index security:

1. Load the required assembly files and data types.

#load "../Initialize.csx"
#load "../QuantConnect.csx"
#r "../Microsoft.Data.Analysis.dll"

using QuantConnect;
using QuantConnect.Data;
using QuantConnect.Algorithm;
using QuantConnect.Research;
using Microsoft.Data.Analysis;

2. Create a QuantBook .

var qb = new QuantBook();

qb = QuantBook()

3. Call the AddIndex method with a ticker and then save a reference to the Index Symbol .

var spx = qb.AddIndex("SPX").Symbol;
var vix = qb.AddIndex("VIX").Symbol;

spx = qb.AddIndex("SPX").Symbol
vix = qb.AddIndex("VIX").Symbol

To view all of the available indices, see Supported Indices .

Get Historical Data

You need a subscription before you can request historical data for a security. On the time dimension, you can request an amount of historical data based on a trailing number of bars, a trailing period of time, or a defined period of time. On the security dimension, you can request historical data for a single Index, a subset of the Indices you created subscriptions for in your notebook, or all of the Indices in your notebook.

Trailing Number of Bars

To get historical data for a number of trailing bars, call the History method with the Symbol object(s) and an integer.

// Slice objects
var singleHistorySlice = qb.History(spx, 10);
var subsetHistorySlice = qb.History(new[] {spx, vix}, 10);
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(spx, 10);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {spx, vix}, 10);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, 10);

# DataFrame
single_history_df = qb.History(spx, 10)
single_history_trade_bar_df = qb.History(TradeBar, spx, 10)
subset_history_df = qb.History([spx, vix], 10)
subset_history_trade_bar_df = qb.History(TradeBar, [spx, vix], 10)
all_history_df = qb.History(qb.Securities.Keys, 10)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, 10)

# Slice objects
all_history_slice = qb.History(10)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](spx, 10)
subset_history_trade_bars = qb.History[TradeBar]([spx, vix], 10)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, 10)

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

Trailing Period of Time

To get historical data for a trailing period of time, call the History method with the Symbol object(s) and a TimeSpan timedelta .

// Slice objects
var singleHistorySlice = qb.History(spx, TimeSpan.FromDays(3));
var subsetHistorySlice = qb.History(new[] {spx, vix}, TimeSpan.FromDays(3));
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(spx, TimeSpan.FromDays(3));
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {spx, vix}, TimeSpan.FromDays(3));
var allHistoryTradeBars = qb.History<TradeBar>(TimeSpan.FromDays(3));

// Tick objects
var singleHistoryTicks = qb.History<Tick>(spx, TimeSpan.FromDays(3), Resolution.Tick);
var subsetHistoryTicks = qb.History<Tick>(new[] {spx, vix}, TimeSpan.FromDays(3), Resolution.Tick);
var allHistoryTicks = qb.History<Tick>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Tick);

# DataFrame of trade data (indices don't have quote data)
single_history_df = qb.History(spx, timedelta(days=3))
subset_history_df = qb.History([spx, vix], timedelta(days=3))
all_history_df = qb.History(qb.Securities.Keys, timedelta(days=3))

# DataFrame of tick data
single_history_tick_df = qb.History(spx, timedelta(days=3), Resolution.Tick)
subset_history_tick_df = qb.History([spx, usb], timedelta(days=3), Resolution.Tick)
all_history_tick_df = qb.History(qb.Securities.Keys, timedelta(days=3), Resolution.Tick)

# Slice objects
all_history_slice = qb.History(timedelta(days=3))

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](spx, timedelta(days=3))
subset_history_trade_bars = qb.History[TradeBar]([spx, vix], timedelta(days=3))
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, timedelta(days=3))

# Tick objects
single_history_ticks = qb.History[Tick](spx, timedelta(days=3), Resolution.Tick)
subset_history_ticks = qb.History[Tick]([spx, vix], timedelta(days=3), Resolution.Tick)
all_history_ticks = qb.History[Tick](qb.Securities.Keys, timedelta(days=3), Resolution.Tick)

The preceding calls return the most recent bars or ticks, excluding periods of time when the exchange was closed.

Defined Period of Time

To get historical data for a specific period of time, call the History method with the Symbol object(s), a start DateTime datetime , and an end DateTime datetime . The start and end times you provide are based in the notebook time zone .

var startTime = new DateTime(2021, 1, 1);
var endTime = new DateTime(2021, 2, 1);

// Slice objects
var singleHistorySlice = qb.History(spx, startTime, endTime);
var subsetHistorySlice = qb.History(new[] {spx, vix}, startTime, endTime);
var allHistorySlice = qb.History(qb.Securities.Keys, startTime, endTime);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>(spx, startTime, endTime);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {spx, vix}, startTime, endTime);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, startTime, endTime);

// Tick objects
var singleHistoryTicks = qb.History<Tick>(spx, startTime, endTime, Resolution.Tick);
var subsetHistoryTicks = qb.History<Tick>(new[] {spx, vix}, startTime, endTime, Resolution.Tick);
var allHistoryTicks = qb.History<Tick>(qb.Securities.Keys, startTime, endTime, Resolution.Tick);

start_time = datetime(2021, 1, 1)
end_time = datetime(2021, 2, 1)

# DataFrame of trade data (indices don't have quote data)
single_history_df = qb.History(spx, start_time, end_time)
subset_history_df = qb.History([spx, vix], start_time, end_time)
all_history_df = qb.History(qb.Securities.Keys, start_time, end_time)

# DataFrame of tick data
single_history_tick_df = qb.History(spx, start_time, end_time, Resolution.Tick)
subset_history_tick_df = qb.History([spx, vix], start_time, end_time, Resolution.Tick)
all_history_tick_df = qb.History(qb.Securities.Keys, start_time, end_time, Resolution.Tick)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar](spx, start_time, end_time)
subset_history_trade_bars = qb.History[TradeBar]([spx, vix], start_time, end_time)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, start_time, end_time)

# Tick objects
single_history_ticks = qb.History[Tick](spx, start_time, end_time, Resolution.Tick)
subset_history_ticks = qb.History[Tick]([spx, vix], start_time, end_time, Resolution.Tick)
all_history_ticks = qb.History[Tick](qb.Securities.Keys, start_time, end_time, Resolution.Tick)

The preceding calls return the bars or ticks that have a timestamp within the defined period of time.

Resolutions

The following table shows the available resolutions and data formats for Index subscriptions:

Resolution	TradeBar	QuoteBar	Trade Tick	Quote Tick
Tick
Second
Minute
Hour
Daily

Markets

The only market available for Indices is Market.USA .

Wrangle Data

You need some historical data to perform wrangling operations. The process to manipulate the historical data depends on its data type. To display pandas objects, run a cell in a notebook with the pandas object as the last line. To display other data formats, call the print method.

You need some historical data to perform wrangling operations. Use LINQ to wrangle the data and then call the Console.WriteLine method in a Jupyter Notebook to display the data. The process to manipulate the historical data depends on its data type.

DataFrame Objects

If the History method returns a DataFrame , the first level of the DataFrame index is the encoded Index Symbol and the second level is the EndTime of the data sample. The columns of the DataFrame are the data properties.

To select the historical data of a single Index, index the loc property of the DataFrame with the Index Symbol .

all_history_df.loc[spx]  # or all_history_df.loc['SPX']

To select a column of the DataFrame , index it with the column name.

all_history_df.loc[spx]['close']

If you request historical data for multiple Indices, you can transform the DataFrame so that it's a time series of close values for all of the Indices. To transform the DataFrame , select the column you want to display for each Index and then call the unstack method.

all_history_df['close'].unstack(level=0)

The DataFrame is transformed so that the column indices are the Symbol of each Index and each row contains the close value.

The historical data methods don't return DataFrame objects, but you can create one for efficient vectorized data wrangling.

using Microsoft.Data.Analysis; 

var columns = new DataFrameColumn[] {
    new PrimitiveDataFrameColumn("Time", history.Select(x => x[spx].EndTime)),
    new DecimalDataFrameColumn("SPX Open", history.Select(x => x[spx].Open)),
    new DecimalDataFrameColumn("SPX High", history.Select(x => x[spx].High)),
    new DecimalDataFrameColumn("SPX Low", history.Select(x => x[spx].Low)),
    new DecimalDataFrameColumn("SPX Close", history.Select(x => x[spx].Close))
};
var df = new DataFrame(columns);
df

To select a particular column of the DataFrame, index it with the column name.

df["SPX close"]

Slice Objects

If the History method returns Slice objects, iterate through the Slice objects to get each one. The Slice objects may not have data for all of your Index subscriptions. To avoid issues, check if the Slice contains data for your Index before you index it with the Index Symbol .

foreach (var slice in allHistorySlice) {
    if (slice.Bars.ContainsKey(spx))
    {
        var tradeBar = slice.Bars[spx];
    }
}

for slice in all_history_slice:
        if slice.Bars.ContainsKey(spx):
        trade_bar = slice.Bars[spx]

You can also iterate through each TradeBar in the Slice .

foreach (var slice in allHistorySlice)
{
    foreach (var kvp in slice.Bars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
}

for slice in all_history_slice:
    for kvp in slice.Bars:
        symbol = kvp.Key
        trade_bar = kvp.Value

You can also use LINQ to select each TradeBar in the Slice for a given Symbol .

var tradeBars = allHistorySlice.Where(slice => slice.Bars.ContainsKey(spx)).Select(slice => slice.Bars[spx]);

TradeBar Objects

If the History method returns TradeBar objects, iterate through the TradeBar objects to get each one.

foreach (var tradeBar in singleHistoryTradeBars)
{
    Console.WriteLine(tradeBar);
}

for trade_bar in single_history_trade_bars:
    print(trade_bar)

If the History method returns TradeBars , iterate through the TradeBars to get the TradeBar of each Index. The TradeBars may not have data for all of your Index subscriptions. To avoid issues, check if the TradeBars object contains data for your security before you index it with the Index Symbol .

foreach (var tradeBars in allHistoryTradeBars)
{
    if (tradeBars.ContainsKey(spx))
    {
        var tradeBar = tradeBars[spx];
    }
}

for trade_bars in all_history_trade_bars:
    if trade_bars.ContainsKey(spx):
        trade_bar = trade_bars[spx]

You can also iterate through each of the TradeBars .

foreach (var tradeBars in allHistoryTradeBars)
{
    foreach (var kvp in tradeBars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
}

for trade_bars in all_history_trade_bars:
    for kvp in trade_bars:
        symbol = kvp.Key
        trade_bar = kvp.Value

Tick Objects

If the History method returns Tick objects, iterate through the Tick objects to get each one.

foreach (var tick in singleHistoryTicks)
{
    Console.WriteLine(tick);
}

for tick in single_history_ticks:
    print(tick)

If the History method returns Ticks , iterate through the Ticks to get the Tick of each Index. The Ticks may not have data for all of your Index subscriptions. To avoid issues, check if the Ticks object contains data for your security before you index it with the Index Symbol .

foreach (var ticks in allHistoryTicks)
{
    if (ticks.ContainsKey(spx))
    {
        var tick = ticks[spx];
    }
}

for ticks in all_history_ticks:
    if ticks.ContainsKey(spx):
        ticks = ticks[spx]

You can also iterate through each of the Ticks .

foreach (var ticks in allHistoryTicks)
{
    foreach (var kvp in ticks)
    {
        var symbol = kvp.Key;
        var tick = kvp.Value;
    }
}

for ticks in all_history_ticks:
    for kvp in ticks:
        symbol = kvp.Key
        tick = kvp.Value

Plot Data

You need some historical Indices data to produce plots. You can use many of the supported plotting libraries Plot.NET package to visualize data in various formats. For example, you can plot candlestick and line charts.

Candlestick Chart

Follow these steps to plot candlestick charts:

1. Get some historical data.

history = qb.History(spx, datetime(2021, 11, 24), datetime(2021, 12, 8), Resolution.Daily).loc[spx]

var history = qb.History<TradeBar>(spx, new DateTime(2021, 11, 24), new DateTime(2021, 12, 8), Resolution.Daily);

2. Import the plotly Plotly.NET library.

import plotly.graph_objects as go

#r "../Plotly.NET.dll"
using Plotly.NET;
using Plotly.NET.LayoutObjects;

3. Create a Candlestick .
   

candlestick = go.Candlestick(x=history.index,
                             open=history['open'],
                             high=history['high'],
                             low=history['low'],
                             close=history['close'])

var chart = Chart2D.Chart.Candlestick<decimal, decimal, decimal, decimal, DateTime, string>(
    history.Select(x => x.Open),
    history.Select(x => x.High),
    history.Select(x => x.Low),
    history.Select(x => x.Close),
    history.Select(x => x.EndTime)
);

4. Create a Layout .
   

layout = go.Layout(title=go.layout.Title(text='SPX OHLC'),
                   xaxis_title='Date',
                   yaxis_title='Price',
                   xaxis_rangeslider_visible=False)

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{spx} OHLC");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

5. Create a Figure .
   

fig = go.Figure(data=[candlestick], layout=layout)

6. Assign the Layout to the chart.
   

chart.WithLayout(layout);

7. Show the Figure .
   

fig.show()

HTML(GenericChart.toChartHTML(chart))

Candlestick charts display the open, high, low, and close prices of the security.

Line Chart

Follow these steps to plot line charts using built-in methods Plotly.NET package :

1. Get some historical data.

history = qb.History([spx, vix], datetime(2021, 11, 24), datetime(2021, 12, 8), Resolution.Daily)

var history = qb.History<TradeBar>(new [] {spx, vix}, new DateTime(2021, 11, 24), new DateTime(2021, 12, 8), Resolution.Daily);

2. Select the data to plot.

pct_change = history['close'].unstack(0).pct_change().dropna()

3. Call the plot method on the pandas object.

pct_change.plot(title="Close Price %Change", figsize=(15, 10))

4. Create Line charts.

var chart1 = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x[spx].EndTime),
    history.Select(x => x[spx].Close - x[spx].Open),
    Name: $"{spx}"
);
var chart2 = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x[vix].EndTime),
    history.Select(x => x[vix].Close - x[vix].Open),
    Name: $"{vix}"
);

5. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{spx} & {vix} Daily Spread");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

6. Combine the charts and assign the Layout to the chart.
   

var chart = Plotly.NET.Chart.Combine(new []{chart1, chart2});
chart.WithLayout(layout);

7. Show the plot.

plt.show()

HTML(GenericChart.toChartHTML(chart))

Line charts display the value of the property you selected in a time series.

Datasets > Index Options

Introduction

This page explains how to request, manipulate, and visualize historical Index Options data.

Create Subscriptions

Follow these steps to subscribe to an Index Option security:

1. Load the required assembly files and data types.

#load "../Initialize.csx"
#load "../QuantConnect.csx"
#r "../Microsoft.Data.Analysis.dll"

using QuantConnect;
using QuantConnect.Data;
using QuantConnect.Data.Market;
using QuantConnect.Algorithm;
using QuantConnect.Securities;
using QuantConnect.Securities.Index;
using QuantConnect.Securities.Option;
using QuantConnect.Research;
using Microsoft.Data.Analysis;

2. Instantiate a QuantBook .

var qb = new QuantBook();

qb = QuantBook()

3. Call the AddIndex method with a ticker and resolution.

var indexSymbol = qb.AddIndex("SPX", Resolution.Minute).Symbol;

index_symbol = qb.AddIndex("SPX", Resolution.Minute).Symbol

To view the available indices, see Supported Assets .

If you do not pass a resolution argument, Resolution.Minute is used by default.


4. Call the AddIndexOption method with the underlying Index Symbol and, if you want non-standard Index Options, the target Option ticker .

var option = qb.AddIndexOption(indexSymbol);

option = qb.AddIndexOption(index_symbol)

5. (Optional) Set a contract filter .

option.SetFilter(-1, 1, 0, 90);

option.SetFilter(-1, 1, 0, 90)

The filter determines which contracts the GetOptionHistory method returns. If you don't set a filter, the default filter selects the contracts that have the following characteristics:

• Standard type (exclude weeklys)
• Within 1 strike price of the underlying asset price
• Expire within 31 days

If you want historical data on individual contracts and their OpenInterest , follow these steps to subscribe to individual Index Option contracts:

1. Call the GetOptionsContractList method with the underlying Index Symbol and a datetime DateTime .

var startDate = new DateTime(2021, 12, 31);

// Standard contracts
var canonicalSymbol = QuantConnect.Symbol.CreateCanonicalOption(indexSymbol, Market.USA, "?SPX");
var contractSymbols = qb.OptionChainProvider.GetOptionContractList(canonicalSymbol, startDate);
            
// Weekly contracts
var weeklyCanonicalSymbol = QuantConnect.Symbol.CreateCanonicalOption(indexSymbol, "SPXW", Market.USA, "?SPXW");
var weeklyContractSymbols = qb.OptionChainProvider.GetOptionContractList(weeklyCanonicalSymbol, startDate)
    .Where(s => OptionSymbol.IsWeekly(s));

start_date = datetime(2021, 12, 31)

# Standard contracts
canonical_symbol = Symbol.CreateCanonicalOption(index_symbol, Market.USA, "?SPX")
contract_symbols = qb.OptionChainProvider.GetOptionContractList(canonical_symbol, start_date)

# Weekly contracts
weekly_canonical_symbol = Symbol.CreateCanonicalOption(index_symbol, "SPXW", Market.USA, "?SPXW")
weekly_contract_symbols = qb.OptionChainProvider.GetOptionContractList(weekly_canonical_symbol, start_date)
weekly_contract_symbols = [s for s in weekly_contract_symbols if OptionSymbol.IsWeekly(s)]

This method returns a list of Symbol objects that reference the Option contracts that were trading at the given time. If you set a contract filter with SetFilter , it doesn't affect the results of GetOptionContractList .

2. Select the Symbol of the OptionContract object(s) for which you want to get historical data.

To filter and select contracts, you can use the following properties of each Symbol object:

Property	Description
ID.Date	The expiration date of the contract.
ID.StrikePrice	The strike price of the contract.
ID.OptionRight	The contract type. The OptionRight enumeration has the following members:
ID.OptionStyle	The contract style. The OptionStyle enumeration has the following members:

// Standard contracts
var contractSymbol = contractSymbols.Where(s => 
    s.ID.OptionRight == OptionRight.Call &&
    s.ID.StrikePrice == 4460 &&
    s.ID.Date == new DateTime(2022, 4, 14)).First();

// Weekly contracts
var weeklyContractSymbol = weeklyContractSymbols.Where(s => 
    s.ID.OptionRight == OptionRight.Call &&
    s.ID.StrikePrice == 4460 &&
    s.ID.Date == new DateTime(2021, 12, 31)).First();

# Standard contracts
contract_symbol = [s for s in contract_symbols 
    if s.ID.OptionRight == OptionRight.Call 
        and s.ID.StrikePrice == 4460 
        and s.ID.Date == datetime(2022, 4, 14)][0]

# Weekly contracts
weekly_contract_symbol = [s for s in weekly_contract_symbols 
    if s.ID.OptionRight == OptionRight.Call 
        and s.ID.StrikePrice == 4460 
        and s.ID.Date == datetime(2021, 12, 31)][0]

3. Call the AddIndexOptionContract method with an OptionContract Symbol and disable fill-forward.

qb.AddIndexOptionContract(contractSymbol, fillForward: false);

qb.AddIndexOptionContract(contract_symbol, fillForward = False)

Disable fill-forward because there are only a few OpenInterest data points per day.

Get Historical Data

You need a subscription before you can request historical data for Index Option contracts. On the time dimension, you can request an amount of historical data based on a trailing number of bars, a trailing period of time, or a defined period of time. On the contract dimension, you can request historical data for a single contract, a subset of the contracts you created subscriptions for in your notebook, or all of the contracts in your notebook.

Before you request historical data, call the SetStartDate method with a datetime DateTime to reduce the risk of look-ahead bias .

qb.SetStartDate(startDate);

qb.SetStartDate(start_date)

If you call the SetStartDate method, the date that you pass to the method is the latest date for which your history requests will return data.

Trailing Number of Bars

To get historical data for a number of trailing bars, call the History method with the contract Symbol object(s) and an integer.

// Slice objects
var singleHistorySlice = qb.History("SPX", 10);
var subsetHistorySlice = qb.History(new[] {"SPX"}, 10);
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>("SPX", 10);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {"SPX"}, 10);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, 10);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>("SPX", 10);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {"SPX"}, 10);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, 10);

// OpenInterest objects
var singleHistoryOpenInterest = qb.History<OpenInterest>("SPX", 400);
var subsetHistoryOpenInterest = qb.History<OpenInterest>(new[] {"SPX"}, 400);
var allHistoryOpenInterest = qb.History<OpenInterest>(qb.Securities.Keys, 400);

# DataFrame of trade and quote data
single_history_df = qb.History("SPX", 10)
subset_history_df = qb.History(["SPX"], 10)
all_history_df = qb.History(qb.Securities.Keys, 10)

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, "SPX", 10)
subset_history_trade_bar_df = qb.History(TradeBar, ["SPX"], 10)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, 10)

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, "SPX", 10)
subset_history_quote_bar_df = qb.History(QuoteBar, ["SPX"], 10)
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, 10)

# DataFrame of open interest data
single_history_open_interest_df = qb.History(OpenInterest, "SPX", 400)
subset_history_open_interest_df = qb.History(OpenInterest, ["SPX"], 400)
all_history_open_interest_df = qb.History(OpenInterest, qb.Securities.Keys, 400)

# Slice objects
all_history_slice = qb.History(10)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar]("SPX", 10)
subset_history_trade_bars = qb.History[TradeBar](["SPX"], 10)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, 10)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar]("SPX", 10)
subset_history_quote_bars = qb.History[QuoteBar](["SPX"], 10)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, 10)

# OpenInterest objects
single_history_open_interest = qb.History[OpenInterest]("SPX", 400)
subset_history_open_interest = qb.History[OpenInterest](["SPX"], 400)
all_history_open_interest = qb.History[OpenInterest](qb.Securities.Keys, 400)

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

Trailing Period of Time

To get historical data for a trailing period of time, call the History method with the contract Symbol object(s) and a TimeSpan timedelta .

// Slice objects
var singleHistorySlice = qb.History("SPX", TimeSpan.FromDays(3));
var subsetHistorySlice = qb.History(new[] {"SPX"}, TimeSpan.FromDays(3));
var allHistorySlice = qb.History(10);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>("SPX", TimeSpan.FromDays(3));
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {"SPX"}, TimeSpan.FromDays(3));
var allHistoryTradeBars = qb.History<TradeBar>(TimeSpan.FromDays(3));

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>("SPX", TimeSpan.FromDays(3), Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {"SPX"}, TimeSpan.FromDays(3), Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, TimeSpan.FromDays(3), Resolution.Minute);


// OpenInterest objects
var singleHistoryOpenInterest = qb.History<OpenInterest>("SPX", TimeSpan.FromDays(2));
var subsetHistoryOpenInterest = qb.History<OpenInterest>(new[] {"SPX"}, TimeSpan.FromDays(2));
var allHistoryOpenInterest = qb.History<OpenInterest>(qb.Securities.Keys, TimeSpan.FromDays(2));

# DataFrame of trade and quote data
single_history_df = qb.History("SPX", timedelta(days=3))
subset_history_df = qb.History(["SPX"], timedelta(days=3))
all_history_df = qb.History(qb.Securities.Keys, timedelta(days=3))

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, "SPX", timedelta(days=3))
subset_history_trade_bar_df = qb.History(TradeBar, ["SPX"], timedelta(days=3))
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, timedelta(days=3))

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, "SPX", timedelta(days=3))
subset_history_quote_bar_df = qb.History(QuoteBar, ["SPX"], timedelta(days=3))
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, timedelta(days=3))

# DataFrame of open interest data
single_history_open_interest_df = qb.History(OpenInterest, "SPX", timedelta(days=3))
subset_history_open_interest_df = qb.History(OpenInterest, ["SPX"], timedelta(days=3))
all_history_open_interest_df = qb.History(OpenInterest, qb.Securities.Keys, timedelta(days=3))

# Slice objects
all_history_slice = qb.History(timedelta(days=3))

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar]("SPX", timedelta(days=3))
subset_history_trade_bars = qb.History[TradeBar](["SPX"], timedelta(days=3))
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, timedelta(days=3))

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar]("SPX", timedelta(days=3), Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar](["SPX"], timedelta(days=3), Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, timedelta(days=3), Resolution.Minute) 


# OpenInterest objects
single_history_open_interest = qb.History[OpenInterest]("SPX", timedelta(days=2))
subset_history_open_interest = qb.History[OpenInterest](["SPX"], timedelta(days=2))
all_history_open_interest = qb.History[OpenInterest](qb.Securities.Keys, timedelta(days=2))

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

Defined Period of Time

To get historical data for individual Index Option contracts during a specific period of time, call the History method with the Index Option contract Symbol object(s), a start DateTime datetime , and an end DateTime datetime . The start and end times you provide are based in the notebook time zone .

var startTime = new DateTime(2021, 12, 1);
var endTime = new DateTime(2021, 12, 31);

// Slice objects
var singleHistorySlice = qb.History("SPX", startTime, endTime);
var subsetHistorySlice = qb.History(new[] {"SPX"}, startTime, endTime);
var allHistorySlice = qb.History(startTime, endTime);

// TradeBar objects
var singleHistoryTradeBars = qb.History<TradeBar>("SPX", startTime, endTime);
var subsetHistoryTradeBars = qb.History<TradeBar>(new[] {"SPX"}, startTime, endTime);
var allHistoryTradeBars = qb.History<TradeBar>(qb.Securities.Keys, startTime, endTime);

// QuoteBar objects
var singleHistoryQuoteBars = qb.History<QuoteBar>("SPX", startTime, endTime, Resolution.Minute);
var subsetHistoryQuoteBars = qb.History<QuoteBar>(new[] {"SPX"}, startTime, endTime, Resolution.Minute);
var allHistoryQuoteBars = qb.History<QuoteBar>(qb.Securities.Keys, startTime, endTime, Resolution.Minute);


// OpenInterest objects
var singleHistoryOpenInterest = qb.History<OpenInterest>("SPX", startTime, endTime);
var subsetHistoryOpenInterest = qb.History<OpenInterest>(new[] {"SPX"}, startTime, endTime);
var allHistoryOpenInterest = qb.History<OpenInterest>(qb.Securities.Keys, startTime, endTime);

start_time = datetime(2021, 12, 1)
end_time = datetime(2021, 12, 31)

# DataFrame of trade and quote data
single_history_df = qb.History("SPX", start_time, end_time)
subset_history_df = qb.History(["SPX"], start_time, end_time)
all_history_df = qb.History(qb.Securities.Keys, start_time, end_time)

# DataFrame of trade data
single_history_trade_bar_df = qb.History(TradeBar, "SPX", start_time, end_time)
subset_history_trade_bar_df = qb.History(TradeBar, ["SPX"], start_time, end_time)
all_history_trade_bar_df = qb.History(TradeBar, qb.Securities.Keys, start_time, end_time)

# DataFrame of quote data
single_history_quote_bar_df = qb.History(QuoteBar, "SPX", start_time, end_time)
subset_history_quote_bar_df = qb.History(QuoteBar, ["SPX"], start_time, end_time)
all_history_quote_bar_df = qb.History(QuoteBar, qb.Securities.Keys, start_time, end_time)

# DataFrame of open interest data
single_history_open_interest_df = qb.History(OpenInterest, "SPX", start_time, end_time)
subset_history_open_interest_df = qb.History(OpenInterest, ["SPX"], start_time, end_time)
all_history_trade_open_interest_df = qb.History(OpenInterest, qb.Securities.Keys, start_time, end_time)

# TradeBar objects
single_history_trade_bars = qb.History[TradeBar]("SPX", start_time, end_time)
subset_history_trade_bars = qb.History[TradeBar](["SPX"], start_time, end_time)
all_history_trade_bars = qb.History[TradeBar](qb.Securities.Keys, start_time, end_time)

# QuoteBar objects
single_history_quote_bars = qb.History[QuoteBar]("SPX", start_time, end_time, Resolution.Minute)
subset_history_quote_bars = qb.History[QuoteBar](["SPX"], start_time, end_time, Resolution.Minute)
all_history_quote_bars = qb.History[QuoteBar](qb.Securities.Keys, start_time, end_time, Resolution.Minute)


# OpenInterest objects
single_history_open_interest = qb.History[OpenInterest]("SPX", start_time, end_time)
subset_history_open_interest = qb.History[OpenInterest](["SPX"], start_time, end_time)
all_history_open_interest = qb.History[OpenInterest](qb.Securities.Keys, start_time, end_time)

To get historical data for all of the Index Option contracts that pass your filter during a specific period of time, call the GetOptionHistory method with the canonical Index Option Symbol object, a start DateTime datetime , and an end DateTime datetime .

option_history = qb.GetOptionHistory(option.Symbol, end_time-timedelta(days=2), end_time, Resolution.Minute, fillForward=False, extendedMarketHours=False)

var optionHistory = qb.GetOptionHistory(option.Symbol, endTime-TimeSpan.FromDays(2), endTime, Resolution.Minute, fillForward: False, extendedMarketHours: False);

The preceding calls return data that have a timestamp within the defined period of time.

Resolutions

The following table shows the available resolutions and data formats for Index Option contract subscriptions:

Resolution	TradeBar	QuoteBar	Trade Tick	Quote Tick
Tick
Second
Minute
Hour
Daily

Markets

The following Market enumeration members are available for Index Options:

Wrangle Data

You need some historical data to perform wrangling operations. The process to manipulate the historical data depends on its data type. To display pandas objects, run a cell in a notebook with the pandas object as the last line. To display other data formats, call the print method.

You need some historical data to perform wrangling operations. Use LINQ to wrangle the data and then call the Console.WriteLine method in a Jupyter Notebook to display the data. The process to manipulate the historical data depends on its data type.

DataFrame Objects

If your history request returns a DataFrame , the DataFrame has the following index levels:

1. Contract expiry
2. Contract strike price
3. Contract type (call or put)
4. Encoded contract Symbol
5. The EndTime of the data sample

The columns of the DataFrame are the data properties. Depending on how you request data, the DataFrame may contain data for the underlying security, which causes some of the index levels to be an empty string for the corresponding rows.

To select the rows of the contract(s) that expire at a specific time, index the loc property of the DataFrame with the expiry time.

all_history_df.loc[datetime(2022, 4, 14)]

If you remove the first three index levels, you can index the DataFrame with just the contract Symbol , similiar to how you would with non-derivative asset classes. To remove the first three index levels, call the droplevel method.

all_history_df.index = all_history_df.index.droplevel([0,1,2])

To select the historical data of a single Index Options contract, index the loc property of the DataFrame with the contract Symbol .

all_history_df.loc[contract_symbol]

To select a column of the DataFrame , index it with the column name.

all_history_df.loc[contract_symbol]['close']

If you request historical data for multiple Index Option contracts, you can transform the DataFrame so that it's a time series of close values for all of the Index Option contracts. To transform the DataFrame , select the column you want to display for each Index Option contract and then call the unstack method.

all_history_df['close'].unstack(level=0)

The DataFrame is transformed so that the column indices are the Symbol of each security and each row contains the close value.

The historical data methods don't return DataFrame objects, but you can create one for efficient vectorized data wrangling.

using Microsoft.Data.Analysis; 

var columns = new DataFrameColumn[] {
    new PrimitiveDataFrameColumn("Time", history.Select(x => x[contractSymbol].EndTime)),
    new DecimalDataFrameColumn(" Open", history.Select(x => x[contractSymbol].Open)),
    new DecimalDataFrameColumn(" High", history.Select(x => x[contractSymbol].High)),
    new DecimalDataFrameColumn(" Low", history.Select(x => x[contractSymbol].Low)),
    new DecimalDataFrameColumn(" Close", history.Select(x => x[contractSymbol].Close))
};
var df = new DataFrame(columns);
df

To select a particular column of the DataFrame, index it with the column name.

df[" close"]

Slice Objects

If the History method returns Slice objects, iterate through the Slice objects to get each one. The Slice objects may not have data for all of your Index Options subscriptions. To avoid issues, check if the Slice contains data for your Index Option contract before you index it with the Index Options Symbol .

foreach (var slice in allHistorySlice) {
    if (slice.Bars.ContainsKey(contractSymbol))
    {
        var tradeBar = slice.Bars[contractSymbol];
    }
    if (slice.QuoteBars.ContainsKey(contractSymbol))
    {
        var quoteBar = slice.QuoteBars[contractSymbol];
    }
}

for slice in all_history_slice:
        if slice.Bars.ContainsKey(contract_symbol):
        trade_bar = slice.Bars[contract_symbol]
    if slice.QuoteBars.ContainsKey(contract_symbol):
        quote_bar = slice.QuoteBars[contract_symbol]

You can also iterate through each TradeBar and QuoteBar in the Slice .

foreach (var slice in allHistorySlice)
{
    foreach (var kvp in slice.Bars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
    foreach (var kvp in slice.QuoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for slice in all_history_slice:
    for kvp in slice.Bars:
        symbol = kvp.Key
        trade_bar = kvp.Value
    for kvp in slice.QuoteBars:
        symbol = kvp.Key
        quote_bar = kvp.Value

You can also use LINQ to select each TradeBar in the Slice for a given Symbol .

var tradeBars = allHistorySlice.Where(slice => slice.Bars.ContainsKey(contractSymbol)).Select(slice => slice.Bars[contractSymbol]);

TradeBar Objects

If the History method returns TradeBar objects, iterate through the TradeBar objects to get each one.

foreach (var tradeBar in singleHistoryTradeBars)
{
    Console.WriteLine(tradeBar);
}

for trade_bar in single_history_trade_bars:
    print(trade_bar)

If the History method returns TradeBars , iterate through the TradeBars to get the TradeBar of each Index Option contract. The TradeBars may not have data for all of your Index Options subscriptions. To avoid issues, check if the TradeBars object contains data for your security before you index it with the Index Options Symbol .

foreach (var tradeBars in allHistoryTradeBars)
{
    if (tradeBars.ContainsKey(contractSymbol))
    {
        var tradeBar = tradeBars[contractSymbol];
    }
}

for trade_bars in all_history_trade_bars:
    if trade_bars.ContainsKey(contract_symbol):
        trade_bar = trade_bars[contract_symbol]

You can also iterate through each of the TradeBars .

foreach (var tradeBars in allHistoryTradeBars)
{
    foreach (var kvp in tradeBars)
    {
        var symbol = kvp.Key;
        var tradeBar = kvp.Value;
    }
}

for trade_bars in all_history_trade_bars:
    for kvp in trade_bars:
        symbol = kvp.Key
        trade_bar = kvp.Value

QuoteBar Objects

If the History method returns QuoteBar objects, iterate through the QuoteBar objects to get each one.

foreach (var quoteBar in singleHistoryQuoteBars)
{
    Console.WriteLine(quoteBar);
}

for quote_bar in single_history_quote_bars:
    print(quote_bar)

If the History method returns QuoteBars , iterate through the QuoteBars to get the QuoteBar of each Index Option contract. The QuoteBars may not have data for all of your Index Options subscriptions. To avoid issues, check if the QuoteBars object contains data for your security before you index it with the Index Options Symbol .

foreach (var quoteBars in allHistoryQuoteBars)
{
    if (quoteBars.ContainsKey(contractSymbol))
    {
        var quoteBar = quoteBars[contractSymbol];
    }
}

for quote_bars in all_history_quote_bars:
    if quote_bars.ContainsKey(contract_symbol):
        quote_bar = quote_bars[contract_symbol]

You can also iterate through each of the QuoteBars .

foreach (var quoteBars in allHistoryQuoteBars)
{
    foreach (var kvp in quoteBars)
    {
        var symbol = kvp.Key;
        var quoteBar = kvp.Value;
    }
}

for quote_bars in all_history_quote_bars:
    for kvp in quote_bars:
        symbol = kvp.Key
        quote_bar = kvp.Value

OpenInterest Objects

If the History method returns OpenInterest objects, iterate through the OpenInterest objects to get each one.

foreach (var openInterest in singleHistoryOpenInterest)
{
    Console.WriteLine(openInterest);
}

for open_interest in single_history_open_interest:
    print(open_interest)

If the History method returns a dictionary of OpenInterest objects, iterate through the dictionary to get the OpenInterest of each Index Option contract. The dictionary of OpenInterest objects may not have data for all of your Index Options contract subscriptions. To avoid issues, check if the dictionary contains data for your contract before you index it with the Index Options contract Symbol .

foreach (var openInterestDict in allHistoryOpenInterest)
{
    if (openInterestDict.ContainsKey(contractSymbol))
    {
        var openInterest = openInterestDict[contractSymbol];
    }
}

for open_interest_dict in all_history_open_interest:
    if open_interest_dict.ContainsKey(contract_symbol):
        open_interest = open_interest_dict[contract_symbol]

You can also iterate through each of the OpenInterest dictionaries.

foreach (var openInterestDict in allHistoryOpenInterest)
{
    foreach (var kvp in openInterestDict)
    {
        var symbol = kvp.Key;
        var openInterest = kvp.Value;
    }
}

for open_interest_dict in all_history_open_interest:
    for kvp in open_interest_dict:
        symbol = kvp.Key
        open_interest = kvp.Value

OptionHistory Objects

The GetOptionHistory method returns an OptionHistory object. To get each slice in the OptionHistory object, iterate through it.

foreach (var slice in optionHistory)
{
    foreach (var kvp in slice.OptionChains)
    {
        var canonicalSymbol = kvp.Key;
        var chain = kvp.Value;
        foreach (var contract in chain)
        {
            
        }
    }
}

for slice in option_history:
    for canonical_symbol, chain in slice.OptionChains.items(): 
        for contract in chain:
            pass

To convert the OptionHistory object to a DataFrame that contains the trade and quote information of each contract and the underlying, call the GetAllData method.

option_history.GetAllData()

To get the expiration dates of all the contracts in an OptionHistory object, call the GetExpiryDates method.

option_history.GetExpiryDates()

To get the strike prices of all the contracts in an OptionHistory object, call the GetStrikes method.

option_history.GetStrikes()

Plot Data

You need some historical Index Options data to produce plots. You can use many of the supported plotting libraries Plot.NET package to visualize data in various formats. For example, you can plot candlestick and line charts.

Candlestick Chart

Follow these steps to plot candlestick charts:

1. Get some historical data.

history = qb.History(contract_symbol, datetime(2021, 12, 30), datetime(2021, 12, 31))

var history = qb.History<QuoteBar>(contractSymbol, new DateTime(2021, 12, 30), new DateTime(2021, 12, 30));

2. Drop the first four index levels of DataFrame that returns.
   

history.index = history.index.droplevel([0,1,2,3])

3. Import the plotly Plotly.NET library.

import plotly.graph_objects as go

#r "../Plotly.NET.dll"
using Plotly.NET;
using Plotly.NET.LayoutObjects;

4. Create a Candlestick .
   

candlestick = go.Candlestick(x=history.index,
                             open=history['open'],
                             high=history['high'],
                             low=history['low'],
                             close=history['close'])

var chart = Chart2D.Chart.Candlestick<decimal, decimal, decimal, decimal, DateTime, string>(
    history.Select(x => x.Open),
    history.Select(x => x.High),
    history.Select(x => x.Low),
    history.Select(x => x.Close),
    history.Select(x => x.EndTime)
);

5. Create a Layout .

layout = go.Layout(title=go.layout.Title(text=f'{symbol.Value} OHLC'),
                   xaxis_title='Date',
                   yaxis_title='Price',
                   xaxis_rangeslider_visible=False)

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{contractSymbol} OHLC");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

6. Create a Figure .
   

fig = go.Figure(data=[candlestick], layout=layout)

7. Assign the Layout to the chart.
   

chart.WithLayout(layout);

8. Show the Figure .
   

fig.show()

HTML(GenericChart.toChartHTML(chart))

The Jupyter Notebook displays a candlestick chart of the Option contract's price.

Line Chart

Follow these steps to plot line charts using built-in methods Plotly.NET package :

1. Get some historical data.

history = qb.History(OpenInterest, contract_symbol, datetime(2021, 12, 1), datetime(2021, 12, 31))

var history = qb.History<OpenInterest>(contractSymbol, new DateTime(2021, 12, 1), new DateTime(2021, 12, 31));

2. Drop the first three index levels of the DataFrame that returns.

history.index = history.index.droplevel([0,1,2])

3. Select the open interest data.

history = history['openinterest'].unstack(level=0).ffill()

4. Rename the column to be the Symbol of each contract.

history.columns = [
    Symbol.GetAlias(SecurityIdentifier.Parse(x), index_symbol)
        for x in history.columns]

5. Call the plot method with a title and figure size.

history.plot(title="Open Interest", figsize=(16, 8))

6. Create Line charts.

var chart = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x.EndTime),
    history.Select(x => x.Value)
);

7. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Open Interest");
Title title = Title.init($"{contractSymbol} Open Interest");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

8. Assign the Layout to the chart.
   

chart.WithLayout(layout);

9. Show the plot.

plt.show()

HTML(GenericChart.toChartHTML(chart))

The Jupyter Notebook displays a line chart of open interest data.

Datasets > Alternative Data

Introduction

This page explains how to request, manipulate, and visualize historical alternative data. This tutorial uses the VIX Daily Price dataset from the CBOE as the example dataset.

Create Subscriptions

Follow these steps to subscribe to an alternative dataset from the Dataset Market :

1. Load the required assembly files and data types.

#load "../Initialize.csx"
#load "../QuantConnect.csx"
#r "../Microsoft.Data.Analysis.dll"

using QuantConnect;
using QuantConnect.Data;
using QuantConnect.Algorithm;
using QuantConnect.Research;
using QuantConnect.DataSource;
using Microsoft.Data.Analysis;

2. Load the dynamic link library (DLL) of the dataset.

To load the DLL of any dataset, type:

#r "../QuantConnect.DataSource.<nameOfAlternativeDatasetClass>.dll"

For example, to load the DLL of the CBOE dataset, type:

#r "../QuantConnect.DataSource.CBOE.dll"

3. Create a QuantBook .

var qb = new QuantBook();

qb = QuantBook()

4. Call the AddData method with the dataset class, a ticker, and a resolution and then save a reference to the alternative data Symbol .

var vix = qb.AddData<CBOE>("VIX", Resolution.Daily).Symbol;
var v3m = qb.AddData<CBOE>("VIX3M", Resolution.Daily).Symbol;

vix = qb.AddData(CBOE, "VIX", Resolution.Daily).Symbol
v3m = qb.AddData(CBOE, "VIX3M", Resolution.Daily).Symbol

To view the arguments that the AddData method accepts for each dataset, see the dataset listing .

If you don't pass a resolution argument, the default resolution of the dataset is used by default. To view the supported resolutions and the default resolution of each dataset, see the dataset listing .

Get Historical Data

You need a subscription before you can request historical data for a dataset. On the time dimension, you can request an amount of historical data based on a trailing number of bars, a trailing period of time, or a defined period of time. On the dataset dimension, you can request historical data for a single dataset subscription, a subset of the dataset subscriptions you created in your notebook, or all of the dataset subscriptions in your notebook.

Trailing Number of Bars

To get historical data for a number of trailing bars, call the History method with the Symbol object(s) and an integer.

// Slice objects
var singleHistorySlice = qb.History(vix, 10);
var subsetHistorySlice = qb.History(new[] {vix, v3m}, 10);
var allHistorySlice = qb.History(10);

// CBOE objects
var singleHistoryDataObjects = qb.History<CBOE>(vix, 10);
var subsetHistoryDataObjects = qb.History<CBOE>(new[] {vix, v3m}, 10);
var allHistoryDataObjects = qb.History<CBOE>(qb.Securities.Keys, 10);

# DataFrame
single_history_df = qb.History(vix, 10)
subset_history_df = qb.History([vix, v3m], 10)
all_history_df = qb.History(qb.Securities.Keys, 10)

# Slice objects
all_history_slice = qb.History(10)

# CBOE objects
single_history_data_objects = qb.History[CBOE](vix, 10)
subset_history_data_objects = qb.History[CBOE]([vix, v3m], 10)
all_history_data_objects = qb.History[CBOE](qb.Securities.Keys, 10)

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

Trailing Period of Time

To get historical data for a trailing period of time, call the History method with the Symbol object(s) and a TimeSpan timedelta .

// Slice objects
var singleHistorySlice = qb.History(vix, TimeSpan.FromDays(3));
var subsetHistorySlice = qb.History(new[] {vix, v3m}, TimeSpan.FromDays(3));
var allHistorySlice = qb.History(10);

// CBOE objects
var singleHistoryDataObjects = qb.History<CBOE>(vix, TimeSpan.FromDays(3));
var subsetHistoryDataObjects = qb.History<CBOE>(new[] {vix, v3m}, TimeSpan.FromDays(3));
var allHistoryDataObjects = qb.History<CBOE>(TimeSpan.FromDays(3));

# DataFrame
single_history_df = qb.History(vix, timedelta(days=3))
subset_history_df = qb.History([vix, v3m], timedelta(days=3))
all_history_df = qb.History(qb.Securities.Keys, timedelta(days=3))

# Slice objects
all_history_slice = qb.History(timedelta(days=3))

# CBOE objects
single_history_data_objects = qb.History[CBOE](vix, timedelta(days=3))
subset_history_data_objects = qb.History[CBOE]([vix, v3m], timedelta(days=3))
all_history_data_objects = qb.History[CBOE](qb.Securities.Keys, timedelta(days=3))

The preceding calls return the most recent bars or ticks, excluding periods of time when the exchange was closed.

Defined Period of Time

To get historical data for a specific period of time, call the History method with the Symbol object(s), a start DateTime datetime , and an end DateTime datetime . The start and end times you provide are based in the notebook time zone .

var startTime = new DateTime(2021, 1, 1);
var endTime = new DateTime(2021, 3, 1);

// Slice objects
var singleHistorySlice = qb.History(vix, startTime, endTime);
var subsetHistorySlice = qb.History(new[] {vix, v3m}, startTime, endTime);
var allHistorySlice = qb.History(startTime, endTime);

// CBOE objects
var singleHistoryDataObjects = qb.History<CBOE>(vix, startTime, endTime);
var subsetHistoryDataObjects = qb.History<CBOE>(new[] {vix, v3m}, startTime, endTime);
var allHistoryDataObjects = qb.History<CBOE>(qb.Securities.Keys, startTime, endTime);

start_time = datetime(2021, 1, 1)
end_time = datetime(2021, 3, 1)

# DataFrame
single_history_df = qb.History(vix, start_time, end_time)
subset_history_df = qb.History([vix, v3m], start_time, end_time)
all_history_df = qb.History(qb.Securities.Keys, start_time, end_time)

# Slice objects
all_history_slice = qb.History(start_time, end_time)

# CBOE objects
single_history_data_objects = qb.History[CBOE](vix, start_time, end_time)
subset_history_data_objects = qb.History[CBOE]([vix, v3m], start_time, end_time)
all_history_data_objects = qb.History[CBOE](qb.Securities.Keys, start_time, end_time)

The preceding calls return the bars or ticks that have a timestamp within the defined period of time.

If you do not pass a resolution to the History method, the History method uses the resolution that the AddData method used when you created the subscription .

Wrangle Data

You need some historical data to perform wrangling operations. The process to manipulate the historical data depends on its data type. To display pandas objects, run a cell in a notebook with the pandas object as the last line. To display other data formats, call the print method.

You need some historical data to perform wrangling operations. Use LINQ to wrangle the data and then call the Console.WriteLine method in a Jupyter Notebook to display the data. The process to manipulate the historical data depends on its data type.

DataFrame Objects

If the History method returns a DataFrame , the first level of the DataFrame index is the encoded dataset Symbol and the second level is the EndTime of the data sample. The columns of the DataFrame are the data properties.

To select the historical data of a single dataset, index the loc property of the DataFrame with the dataset Symbol .

all_history_df.loc[vix]  # or all_history_df.loc['VIX']

To select a column of the DataFrame , index it with the column name.

all_history_df.loc[vix]['close']

If you request historical data for multiple tickers, you can transform the DataFrame so that it's a time series of close values for all of the tickers. To transform the DataFrame , select the column you want to display for each ticker and then call the unstack method.

all_history_df['close'].unstack(level=0)

The DataFrame is transformed so that the column indices are the Symbol of each ticker and each row contains the close value.

The historical data methods don't return DataFrame objects, but you can create one for efficient vectorized data wrangling.

using Microsoft.Data.Analysis; 

var columns = new DataFrameColumn[] {
    new PrimitiveDataFrameColumn("Time", history.Select(x => x[vix].EndTime)),
    new DecimalDataFrameColumn("VIX Open", history.Select(x => x[vix].Open)),
    new DecimalDataFrameColumn("VIX High", history.Select(x => x[vix].High)),
    new DecimalDataFrameColumn("VIX Low", history.Select(x => x[vix].Low)),
    new DecimalDataFrameColumn("VIX Close", history.Select(x => x[vix].Close))
};
var df = new DataFrame(columns);
df

To select a particular column of the DataFrame, index it with the column name.

df["VIX close"]

Slice Objects

If the History method returns Slice objects, iterate through the Slice objects to get each one. The Slice objects may not have data for all of your dataset subscriptions. To avoid issues, check if the Slice contains data for your ticker before you index it with the dataset Symbol .

foreach (var slice in allHistorySlice) {
    if (slice.ContainsKey(vix))
    {
        var data = slice[vix];
    }
}

for slice in all_history_slice:
        if slice.ContainsKey(vix):
        data = slice[vix]

Plot Data

You need some historical alternative data to produce plots. You can use many of the supported plotting libraries Plot.NET package to visualize data in various formats. For example, you can plot candlestick and line charts.

Candlestick Chart

You can only create candlestick charts for alternative datasets that have open, high, low, and close properties.

Follow these steps to plot candlestick charts:

1. Get some historical data.

history = qb.History(vix, datetime(2021, 1, 1), datetime(2021, 2, 1)).loc[vix]

var history = qb.History<CBOE>(vix, new DateTime(2021, 12, 1), new DateTime(2021, 12, 31));

2. Import the plotly Plotly.NET library.

import plotly.graph_objects as go

#r "../Plotly.NET.dll"
using Plotly.NET;
using Plotly.NET.LayoutObjects;

3. Create a Candlestick .
   

candlestick = go.Candlestick(x=history.index,
                             open=history['open'],
                             high=history['high'],
                             low=history['low'],
                             close=history['close'])

var chart = Chart2D.Chart.Candlestick<decimal, decimal, decimal, decimal, DateTime, string>(
    history.Select(x => x.Open),
    history.Select(x => x.High),
    history.Select(x => x.Low),
    history.Select(x => x.Close),
    history.Select(x => x.EndTime)
);

4. Create a Layout .
   

layout = go.Layout(title=go.layout.Title(text='VIX from CBOE OHLC'),
                   xaxis_title='Date',
                   yaxis_title='Price',
                   xaxis_rangeslider_visible=False)

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{vix} OHLC");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

5. Create a Figure .
   

fig = go.Figure(data=[candlestick], layout=layout)

6. Assign the Layout to the chart.
   

chart.WithLayout(layout);

7. Show the Figure .
   

fig.show()

HTML(GenericChart.toChartHTML(chart))

Candlestick charts display the open, high, low, and close prices of the alternative data.

Line Chart

Follow these steps to plot line charts using built-in methods Plotly.NET package :

1. Get some historical data.

history = qb.History([vix, v3m], datetime(2021, 1, 1), datetime(2021, 2, 1))

var history = qb.History<CBOE>(new [] {vix, v3x}, new DateTime(2021, 1, 1), new DateTime(2021, 2, 1));

2. Select the data to plot.

values = history['close'].unstack(0)

3. Call the plot method on the pandas object.

values.plot(title = 'Close', figsize=(15, 10))

4. Create Line charts.

var chart1 = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x[vix].EndTime),
    history.Select(x => x[vix].Close),
    Name: $"{vix}"
);
var chart2 = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x[v3m].EndTime),
    history.Select(x => x[v3m].Close),
    Name: $"{v3m}"
);

5. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{vix} & {v3m} Close Price");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

6. Combine the charts and assign the Layout to the chart.
   

var chart = Plotly.NET.Chart.Combine(new []{chart1, chart2});
chart.WithLayout(layout);

7. Show the plot.

plt.show()

HTML(GenericChart.toChartHTML(chart))

Line charts display the value of the property you selected in a time series.

Datasets > Custom Data

Introduction

This page explains how to request, manipulate, and visualize historical user-defined custom data.

Define Custom Data

You must format the data file into chronological order before you define the custom data class.

To define a custom data class, extend the BaseData PythonData class and override the GetSource and Reader methods.

#load "../Initialize.csx"
#load "../QuantConnect.csx"
#r "../Microsoft.Data.Analysis.dll"

using QuantConnect;
using QuantConnect.Data;
using QuantConnect.Algorithm;
using QuantConnect.Research;
using Microsoft.Data.Analysis;

public class Nifty : BaseData
{
    public decimal Open;
    public decimal High;
    public decimal Low;
    public decimal Close;

    public Nifty()
    {
    }

    public override SubscriptionDataSource GetSource(SubscriptionDataConfig config, DateTime date, bool isLiveMode)
    {
        var url = "http://cdn.quantconnect.com.s3.us-east-1.amazonaws.com/uploads/CNXNIFTY.csv";
        return new SubscriptionDataSource(url, SubscriptionTransportMedium.RemoteFile);
    }

    public override BaseData Reader(SubscriptionDataConfig config, string line, DateTime date, bool isLiveMode)
    {
        var index = new Nifty();
        index.Symbol = config.Symbol;

        try
        {
            //Example File Format:
            //Date,       Open       High        Low       Close     Volume      Turnover
            //2011-09-13  7792.9    7799.9     7722.65    7748.7    116534670    6107.78
            var data = line.Split(',');
            index.Time = DateTime.Parse(data[0], CultureInfo.InvariantCulture);
            index.EndTime = index.Time.AddDays(1);
            index.Open = Convert.ToDecimal(data[1], CultureInfo.InvariantCulture);
            index.High = Convert.ToDecimal(data[2], CultureInfo.InvariantCulture);
            index.Low = Convert.ToDecimal(data[3], CultureInfo.InvariantCulture);
            index.Close = Convert.ToDecimal(data[4], CultureInfo.InvariantCulture);
            index.Value = index.Close;
        }
        catch
        {
             // Do nothing
        }
        return index;
    }
}

class Nifty(PythonData):
    '''NIFTY Custom Data Class'''
    def GetSource(self, config: SubscriptionDataConfig, date: datetime, isLiveMode: bool) -> SubscriptionDataSource:
        url = "http://cdn.quantconnect.com.s3.us-east-1.amazonaws.com/uploads/CNXNIFTY.csv"
        return SubscriptionDataSource(url, SubscriptionTransportMedium.RemoteFile)

    def Reader(self, config: SubscriptionDataConfig, line: str, date: datetime, isLiveMode: bool) -> BaseData:
        if not (line.strip() and line[0].isdigit()): return None

        # New Nifty object
        index = Nifty()
        index.Symbol = config.Symbol

        try:
            # Example File Format:
            # Date,       Open       High        Low       Close     Volume      Turnover
            # 2011-09-13  7792.9    7799.9     7722.65    7748.7    116534670    6107.78
            data = line.split(',')
            index.Time = datetime.strptime(data[0], "%Y-%m-%d")
            index.EndTime = index.Time + timedelta(days=1)
            index.Value = data[4]
            index["Open"] = float(data[1])
            index["High"] = float(data[2])
            index["Low"] = float(data[3])
            index["Close"] = float(data[4])

        except:
            pass

        return index

Create Subscriptions

You need to define a custom data class before you can subscribe to it.

Follow these steps to subscribe to custom dataset:

1. Create a QuantBook .

var qb = new QuantBook();

qb = QuantBook()

2. Call the AddData method with a ticker and then save a reference to the data Symbol .

var symbol = qb.AddData<Nifty>("NIFTY").Symbol;

symbol = qb.AddData(Nifty, "NIFTY").Symbol

Custom data has its own resolution, so you don't need to specify it.

Get Historical Data

You need a subscription before you can request historical data for a security. You can request an amount of historical data based on a trailing number of bars, a trailing period of time, or a defined period of time.

Before you request data, call SetStartDate method with a datetime DateTime to reduce the risk of look-ahead bias .

qb.SetStartDate(2014, 7, 29);

qb.SetStartDate(2014, 7, 29)

If you call the SetStartDate method, the date that you pass to the method is the latest date for which your history requests will return data.

Trailing Number of Bars

Call the History method with a symbol, integer, and resolution to request historical data based on the given number of trailing bars and resolution.

var history = qb.History(symbol, 10);

history = qb.History(symbol, 10)

This method returns the most recent bars, excluding periods of time when the exchange was closed.

Trailing Period of Time

Call the History method with a symbol, TimeSpan timedelta , and resolution to request historical data based on the given trailing period of time and resolution.

var history = qb.History(symbol, TimeSpan.FromDays(10));

history = qb.History(symbol, timedelta(days=10))

This method returns the most recent bars, excluding periods of time when the exchange was closed.

Defined Period of Time

Call the History method with a symbol, start DateTime datetime , end DateTime datetime , and resolution to request historical data based on the defined period of time and resolution. The start and end times you provide are based in the notebook time zone .

var startTime = new DateTime(2013, 7, 29);
var endTime = new DateTime(2014, 7, 29);
var history = qb.History(symbol, startTime, endTime);

start_time = datetime(2013, 7, 29)
end_time = datetime(2014, 7, 29)
history = qb.History(symbol, start_time, end_time)

This method returns the bars that are timestamped within the defined period of time.

In all of the cases above, the History method returns a DataFrame with a MultiIndex .

In all of the cases above, the History method returns an IEnumerable<Nifty> for single-security requests.

Download Method

To download the data directly from the remote file location instead of using your custom data class, call the Download method with the data URL.

var content = qb.Download("http://cdn.quantconnect.com.s3.us-east-1.amazonaws.com/uploads/CNXNIFTY.csv");

content = qb.Download("http://cdn.quantconnect.com.s3.us-east-1.amazonaws.com/uploads/CNXNIFTY.csv")

Follow these steps to convert the content to a DataFrame :

1. Import the StringIO from the io library.

from io import StringIO

2. Create a StringIO .

data = StringIO(content)

3. Call the read_csv method.

dataframe = pd.read_csv(data, index_col=0)

Wrangle Data

You need some historical data to perform wrangling operations. To display pandas objects, run a cell in a notebook with the pandas object as the last line. To display other data formats, call the print method.

You need some historical data to perform wrangling operations. Use LINQ to wrangle the data and then call the Console.WriteLine method in a Jupyter Notebook to display the data.

The DataFrame that the History method returns has the following index levels:

1. Dataset Symbol
2. The EndTime of the data sample

The columns of the DataFrame are the data properties.

To select the data of a single dataset, index the loc property of the DataFrame with the data Symbol .

history.loc[symbol]

To select a column of the DataFrame , index it with the column name.

history.loc[symbol]['close']

To get each custom data object, iterate through the result of the history request.

foreach(var nifty in history)
{
    Console.WriteLine($"{nifty} EndTime: {nifty.EndTime}");
}

Plot Data

You need some historical custom data to produce plots. You can use many of the supported plotting libraries Plot.NET package to visualize data in various formats. For example, you can plot candlestick and line charts.

Candlestick Chart

Follow these steps to plot candlestick charts:

1. Import the plotly Plotly.NET library.

import plotly.graph_objects as go

#r "../Plotly.NET.dll"
using Plotly.NET;
using Plotly.NET.LayoutObjects;

2. Select the data:

history = history.loc[symbol]

var history = qb.History<Nifty>(symbol, new DateTime(2013, 7, 1), new DateTime(2014, 7, 31));

3. Create a Candlestick .
   

candlestick = go.Candlestick(x=history.index,
                             open=history['open'],
                             high=history['high'],
                             low=history['low'],
                             close=history['close'])

var chart = Chart2D.Chart.Candlestick<decimal, decimal, decimal, decimal, DateTime, string>(
    history.Select(x => x.Open),
    history.Select(x => x.High),
    history.Select(x => x.Low),
    history.Select(x => x.Close),
    history.Select(x => x.EndTime)
);

4. Create a Layout .
   

layout = go.Layout(title=go.layout.Title(text=f'{symbol} OHLC'),
                   xaxis_title='Date',
                   yaxis_title='Price',
                   xaxis_rangeslider_visible=False)

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{symbol} OHLC");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

5. Create a Figure .
   

fig = go.Figure(data=[candlestick], layout=layout)

6. Assign the Layout to the chart.
   

chart.WithLayout(layout);

7. Show the Figure .
   

fig.show()

HTML(GenericChart.toChartHTML(chart))

Candlestick charts display the open, high, low, and close prices of the security.

Line Chart

Follow these steps to plot line charts using built-in methods Plotly.NET package :

1. Select data to plot.

values = history['value'].unstack(level=0)

2. Call the plot method on the pandas object.

values.plot(title="Value", figsize=(15, 10))

3. Create a Line chart.

var chart = Chart2D.Chart.Line<DateTime, decimal, string>(
    history.Select(x => x.EndTime),
    history.Select(x => x.Close)
);

4. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{symbol} Close");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

5. Assign the Layout to the chart.
   

chart.WithLayout(layout);

6. Show the plot.

plt.show()

HTML(GenericChart.toChartHTML(chart))

Line charts display the value of the property you selected in a time series.

Charting

Charting > Bokeh

Introduction

bokeh is a Python library you can use to create interactive visualizations. It helps you build beautiful graphics, ranging from simple plots to complex dashboards with streaming datasets. With bokeh , you can create JavaScript-powered visualizations without writing any JavaScript.

Import Libraries

Follow these steps to import the libraries that you need:

1. Import the bokeh library.

from bokeh.plotting import figure, show
from bokeh.models import BasicTicker, ColorBar, ColumnDataSource, LinearColorMapper
from bokeh.palettes import Category20c
from bokeh.transform import cumsum, transform
from bokeh.io import output_notebook

2. Call the output_notebook method.

output_notebook()

3. Import the numpy library.

import numpy as np

Get Historical Data

Get some historical market data to produce the plots. For example, to get data for a bank sector ETF and some banking companies over 2021, run:

qb = QuantBook()
tickers = ["XLF",   # Financial Select Sector SPDR Fund
           "COF",   # Capital One Financial Corporation
           "GS",    # Goldman Sachs Group, Inc.
           "JPM",   # J P Morgan Chase & Co
           "WFC"]   # Wells Fargo & Company   
symbols = [qb.AddEquity(ticker, Resolution.Daily).Symbol for ticker in tickers]
history = qb.History(symbols, datetime(2021, 1, 1), datetime(2022, 1, 1))

Create Candlestick Chart

You must import the plotting libraries and get some historical data to create candlestick charts.

In this example, you create a candlestick chart that shows the open, high, low, and close prices of one of the banking securities. Follow these steps to create the candlestick chart:

1. Select a Symbol .

symbol = symbols[0]

2. Slice the history DataFrame with the symbol .

data = history.loc[symbol]

3. Divide the data into days with positive returns and days with negative returns.

up_days = data[data['close'] > data['open']]
down_days = data[data['open'] > data['close']]

4. Call the figure function with a title, axis labels and x-axis type.

plot = figure(title=f"{symbol} OHLC", x_axis_label='Date', y_axis_label='Price', x_axis_type='datetime')

5. Call the segment method with the data timestamps, high prices, low prices, and a color.

plot.segment(data.index, data['high'], data.index, data['low'], color="black")

This method call plots the candlestick wicks.

6. Call the vbar method for the up and down days with the data timestamps, open prices, close prices, and a color.

width = 12*60*60*1000
plot.vbar(up_days.index, width, up_days['open'], up_days['close'], 
          fill_color="green", line_color="green")
plot.vbar(down_days.index, width, down_days['open'], down_days['close'],
          fill_color="red", line_color="red")

This method call plots the candlestick bodies.

7. Call the show function.

show(plot)

The Jupyter Notebook displays the candlestick chart.

Create Line Plot

You must import the plotting libraries and get some historical data to create line charts.

In this example, you create a line chart that shows the closing price for one of the banking securities. Follow these steps to create the line chart:

1. Select a Symbol .

symbol = symbols[0]

2. Slice the history DataFrame with the symbol and then select the close column.

close_prices = history.loc[symbol]['close']

3. Call the figure function with title, axis labels and x-axis type..

plot = figure(title=f"{symbol} Close Price", x_axis_label='Date', y_axis_label='Price', x_axis_type='datetime')

4. Call the line method with the timestamps, close_prices , and some design settings.

plot.line(close_prices.index, close_prices, 
          legend_label=symbol.Value, color="blue", line_width=2)

5. Call the show function.

show(plot)

The Jupyter Notebook displays the line plot.

Create Scatter Plot

You must import the plotting libraries and get some historical data to create scatter plots.

In this example, you create a scatter plot that shows the relationship between the daily returns of two banking securities. Follow these steps to create the scatter plot:

1. Select 2 Symbol s.

For example, to select the Symbol s of the first 2 bank stocks, run:

symbol1 = symbols[1]
symbol2 = symbols[2]

2. Slice the history DataFrame with each Symbol and then select the close column.

close_price1 = history.loc[symbol1]['close']
close_price2 = history.loc[symbol2]['close']

3. Call the pct_change and dropna methods on each Series .

daily_return1 = close_price1.pct_change().dropna()
daily_return2 = close_price2.pct_change().dropna()

4. Call the polyfit method with the daily_returns1 , daily_returns2 , and a degree.

m, b = np.polyfit(daily_returns1, daily_returns2, deg=1)

This method call returns the slope and intercept of the ordinary least squares regression line.

5. Call the linspace method with the minimum and maximum values on the x-axis.

x = np.linspace(daily_returns1.min(), daily_returns1.max())

6. Calculate the y-axis coordinates of the regression line.

y = m*x + b

7. Call the figure function with a title and axis labels.

plot = figure(title=f"{symbol1} vs {symbol2} Daily Return", 
              x_axis_label=symbol1.Value, y_axis_label=symbol2.Value)

8. Call the line method with x- and y-axis values, a color, and a line width.

plot.line(x, y, color="red", line_width=2)

This method call plots the regression line.

9. Call the dot method with the daily_returns1 , daily_returns2 , and some design settings.

plot.dot(daily_returns1, daily_returns2, size=20, color="navy", alpha=0.5)

This method call plots the scatter plot dots.

10. Call the show function.

show(plot)

The Jupyter Notebook displays the scatter plot.

Create Histogram

You must import the plotting libraries and get some historical data to create histograms.

In this example, you create a histogram that shows the distribution of the daily percent returns of the bank sector ETF. In addition to the bins in the histogram, you overlay a normal distribution curve for comparison. Follow these steps to create the histogram:

1. Select the Symbol .

symbol = symbols[0]

2. Slice the history DataFrame with the symbol and then select the close column.

close_prices = history.loc[symbol]['close']

3. Call the pct_change method and then call the dropna method.

daily_returns = close_prices.pct_change().dropna()

4. Call the histogram method with the daily_returns , the density argument enabled, and a number of bins.

hist, edges = np.histogram(daily_returns, density=True, bins=20)

This method call returns the following objects:

• hist : The value of the probability density function at each bin, normalized such that the integral over the range is 1.
• edges : The x-axis value of the edges of each bin.

plot = figure(title=f"{symbol} Daily Return Distribution", 
              x_axis_label='Return', y_axis_label='Frequency')

plot.quad(top=hist, bottom=0, left=edges[:-1], right=edges[1:],
          fill_color="navy", line_color="white", alpha=0.5)

This method call plots the histogram bins.

mean = daily_returns.mean()
std = daily_returns.std()

x = np.linspace(-3*std, 3*std, 1000)

pdf = 1/(std * np.sqrt(2*np.pi)) * np.exp(-(x-mean)**2 / (2*std**2))

plot.line(x, pdf, color="red", line_width=4, 
          alpha=0.7, legend_label="Normal Distribution PDF")

This method call plots the normal distribution PDF curve.

show(plot)

The Jupyter Notebook displays the histogram.

Create Bar Chart

You must import the plotting libraries and get some historical data to create bar charts.

In this example, you create a bar chart that shows the average daily percent return of the banking securities. Follow these steps to create the bar chart:

1. Select the close column and then call the unstack method.

close_prices = history['close'].unstack(level=0)

2. Call the pct_change method and then multiply by 100.

daily_returns = close_prices.pct_change() * 100

3. Call the mean method.

avg_daily_returns = daily_returns.mean()

4. Call the DataFrame constructor with the data Series and then call the reset_index method.

avg_daily_returns = pd.DataFrame(avg_daily_returns, columns=['avg_return']).reset_index()

5. Call the figure function with a title, x-axis values, and axis labels.

plot = figure(title='Banking Stocks Average Daily % Returns', x_range=avg_daily_returns['symbol'], 
              x_axis_label='%', y_axis_label='Stocks')

6. Call the vbar method with the avg_daily_returns , x- and y-axis column names, and a bar width.

plot.vbar(source=avg_daily_returns, x='symbol', top='avg_return', width=0.8)

7. Rotate the x-axis label and then call the show function.
   

plot.xaxis.major_label_orientation = 0.6
show(plot)

The Jupyter Notebook displays the bar chart.

Create Heat Map

You must import the plotting libraries and get some historical data to create heat maps.

In this example, you create a heat map that shows the correlation between the daily returns of the banking securities. Follow these steps to create the heat map:

1. Select the close column and then call the unstack method.

close_prices = history['close'].unstack(level=0)

2. Call the pct_change method.

daily_returns = close_prices.pct_change()

3. Call the corr method.

corr_matrix = daily_returns.corr()

4. Set the index and columns of the corr_matrix to the ticker of each security and then set the name of the column and row indices.

corr_matrix.index = corr_matrix.columns = [symbol.Value for symbol in symbols]
corr_matrix.index.name = 'symbol'
corr_matrix.columns.name = "stocks"

5. Call the stack , rename , and reset_index methods.

corr_matrix = corr_matrix.stack().rename("value").reset_index()

6. Call the figure function with a title, axis ticks, and some design settings.

plot = figure(title=f"Banking Stocks and Bank Sector ETF Correlation Heat Map",
              x_range=list(corr_matrix.symbol.drop_duplicates()),
              y_range=list(corr_matrix.stocks.drop_duplicates()),
              toolbar_location=None,
              tools="",
              x_axis_location="above")

7. Select a color palette and then call the LinearColorMapper constructor with the color pallet, the minimum correlation, and the maximum correlation.

colors = Category20c[len(corr_matrix.columns)]
mapper = LinearColorMapper(palette=colors, low=corr_matrix.value.min(), 
                           high=corr_matrix.value.max())

8. Call the rect method with the correlation plot data and design setting.

plot.rect(source=ColumnDataSource(corr_matrix), 
          x="stocks", 
          y="symbol",
          width=1,
          height=1,
          line_color=None,
          fill_color=transform('value', mapper))

9. Call the ColorBar constructor with the mapper , a location, and a BaseTicker .

color_bar = ColorBar(color_mapper=mapper,
                    location=(0, 0),
                    ticker=BasicTicker(desired_num_ticks=len(colors)))

This snippet creates a color bar to represent the correlation coefficients of the heat map cells.

10. Call the add_layout method with the color_bar and a location.

plot.add_layout(color_bar, 'right')

This method call plots the color bar to the right of the heat map.

11. Call the show function.

show(plot)

The Jupyter Notebook displays the heat map.

Create Pie Chart

You must import the plotting libraries and get some historical data to create pie charts.

In this example, you create a pie chart that shows the weights of the banking securities in a portfolio if you allocate to them based on their inverse volatility. Follow these steps to create the pie chart:

1. Select the close column and then call the unstack method.

close_prices = history['close'].unstack(level=0)

2. Call the pct_change method.

daily_returns = close_prices.pct_change()

3. Call the var method, take the inverse, and then normalize the result.

inverse_variance = 1 / daily_returns.var()
inverse_variance /= np.sum(inverse_variance)   # Normalization
inverse_variance *= np.pi*2    # For a full circle circumference in radian

4. Call the DataFrame constructor with the inverse_variance Series and then call the reset_index method.

inverse_variance = pd.DataFrame(inverse_variance, columns=["inverse variance"]).reset_index()

5. Add a color column to the inverse_variance DataFrame .

inverse_variance['color'] = Category20c[len(inverse_variance.index)]

6. Call the figure function with a title.

plot = figure(title=f"Banking Stocks and Bank Sector ETF Allocation")

7. Call the wedge method with design settings and the inverse_variance DataFrame .

plot.wedge(x=0, y=1, radius=0.6, start_angle=cumsum('inverse variance', include_zero=True), 
           end_angle=cumsum('inverse variance'), line_color="white", fill_color='color', 
           legend_field='symbol', source=inverse_variance)

8. Call the show function.

show(plot)

The Jupyter Notebook displays the pie chart.

Charting > Matplotlib

Introduction

matplotlib is the most popular 2d-charting library for python. It allows you to easily create histograms, scatter plots, and various other charts. In addition, pandas is integrated with matplotlib , so you can seamlessly move between data manipulation and data visualization. This makes matplotlib great for quickly producing a chart to visualize your data.

Import Libraries

Follow these steps to import the libraries that you need:

1. Import the matplotlib , mplfinance , and numpy libraries.

import matplotlib.pyplot as plt
import mplfinance
import numpy as np

2. Import, and then call, the register_matplotlib_converters method.

from pandas.plotting import register_matplotlib_converters
register_matplotlib_converters()

Get Historical Data

Get some historical market data to produce the plots. For example, to get data for a bank sector ETF and some banking companies over 2021, run:

qb = QuantBook()
tickers = ["XLF",   # Financial Select Sector SPDR Fund
           "COF",   # Capital One Financial Corporation
           "GS",    # Goldman Sachs Group, Inc.
           "JPM",   # J P Morgan Chase & Co
           "WFC"]   # Wells Fargo & Company   
symbols = [qb.AddEquity(ticker, Resolution.Daily).Symbol for ticker in tickers]
history = qb.History(symbols, datetime(2021, 1, 1), datetime(2022, 1, 1))

Create Candlestick Chart

You must import the plotting libraries and get some historical data to create candlestick charts.

In this example, we'll create a candlestick chart that shows the open, high, low, and close prices of one of the banking securities. Follow these steps to create the candlestick chart:

1. Select a Symbol .

symbol = symbols[0]

2. Slice the history DataFrame with the symbol .

data = history.loc[symbol]

3. Rename the columns.

data.columns = ['Close', 'High', 'Low', 'Open', 'Volume']

4. Call the plot method with the data , chart type, style, title, y-axis label, and figure size.

mplfinance.plot(data,
                type='candle',
                style='charles',
                title=f'{symbol.Value} OHLC',
                ylabel='Price ($)',
                figratio=(15, 10))

The Jupyter Notebook displays the candlestick chart.

Create Line Plot

You must import the plotting libraries and get some historical data to create line charts.

In this example, you create a line chart that shows the closing price for one of the banking securities. Follow these steps to create the line chart:

1. Select a Symbol .

symbol = symbols[0]

2. Slice the history DataFrame with symbol and then select the close column.

data = history.loc[symbol]['close']

3. Call the plot method with a title and figure size.

data.plot(title=f"{symbol} Close Price", figsize=(15, 10));

The Jupyter Notebook displays the line plot.

Create Scatter Plot

You must import the plotting libraries and get some historical data to create scatter plots.

In this example, you create a scatter plot that shows the relationship between the daily returns of two banking securities. Follow these steps to create the scatter plot:

1. Select the 2 Symbol s.

For example, to select the Symbol s of the first 2 bank stocks, run:

symbol1 = symbols[1]
symbol2 = symbols[2]

2. Slice the history DataFrame with each Symbol and then select the close column.

close_price1 = history.loc[symbol1]['close']
close_price2 = history.loc[symbol2]['close']

3. Call the pct_change and dropna methods on each Series .

daily_returns1 = close_price1.pct_change().dropna()
daily_returns2 = close_price2.pct_change().dropna()

4. Call the polyfit method with the daily_returns1 , daily_returns2 , and a degree.

m, b = np.polyfit(daily_returns1, daily_returns2, deg=1)

This method call returns the slope and intercept of the ordinary least squares regression line.

5. Call the linspace method with the minimum and maximum values on the x-axis.

x = np.linspace(daily_returns1.min(), daily_returns1.max())

6. Calculate the y-axis coordinates of the regression line.

y = m*x + b

7. Call the plot method with the coordinates and color of the regression line.

plt.plot(x, y, color='red')

8. In the same cell that you called the plot method, call the scatter method with the 2 daily return series.

plt.scatter(daily_returns1, daily_returns2)

9. In the same cell that you called the scatter method, call the title , xlabel , and ylabel methods with a title and axis labels.

plt.title(f'{symbol1} vs {symbol2} daily returns Scatter Plot')
plt.xlabel(symbol1.Value)
plt.ylabel(symbol2.Value);

The Jupyter Notebook displays the scatter plot.

Create Histogram

You must import the plotting libraries and get some historical data to create histograms.

In this example, you create a histogram that shows the distribution of the daily percent returns of the bank sector ETF. In addition to the bins in the histogram, you overlay a normal distribution curve for comparison. Follow these steps to create the histogram:

1. Select the Symbol .

symbol = symbols[0]

2. Slice the history DataFrame with the symbol and then select the close column.

close_prices = history.loc[symbol]['close']

3. Call the pct_change method and then call the dropna method.

daily_returns = close_prices.pct_change().dropna()

4. Call the mean and std methods.

mean = daily_returns.mean()
std = daily_returns.std()

5. Call the linspace method with the lower limit, upper limit, and number data points for the x-axis of the normal distribution curve.

x = np.linspace(-3*std, 3*std, 1000)

6. Calculate the y-axis values of the normal distribution curve.

pdf = 1/(std * np.sqrt(2*np.pi)) * np.exp(-(x-mean)**2 / (2*std**2))

7. Call the plot method with the data for the normal distribution curve.

plt.plot(x, pdf, label="Normal Distribution")

8. In the same cell that you called the plot method, call the hist method with the daily return data and the number of bins.

plt.hist(daily_returns, bins=20)

9. In the same cell that you called the hist method, call the title , xlabel , and ylabel methods with a title and the axis labels.

plt.title(f'{symbol} Return Distribution')
plt.xlabel('Daily Return')
plt.ylabel('Count');

The Jupyter Notebook displays the histogram.

Create Bar Chart

You must import the plotting libraries and get some historical data to create bar charts.

In this example, you create a bar chart that shows the average daily percent return of the banking securities. Follow these steps to create the bar chart:

1. Select the close column and then call the unstack method.

close_prices = history['close'].unstack(level=0)

2. Call the pct_change method and then multiply by 100.

daily_returns = close_prices.pct_change() * 100

3. Call the mean method.

avg_daily_returns = daily_returns.mean()

4. Call the figure method with a figure size.

plt.figure(figsize=(15, 10))

5. Call the bar method with the x-axis and y-axis values.

plt.bar(avg_daily_returns.index, avg_daily_returns)

6. In the same cell that you called the bar method, call the title , xlabel , and ylabel methods with a title and the axis labels.

plt.title('Banking Stocks Average Daily % Returns')
plt.xlabel('Tickers')
plt.ylabel('%');

The Jupyter Notebook displays the bar chart.

Create Heat Map

You must import the plotting libraries and get some historical data to create heat maps.

In this example, you create a heat map that shows the correlation between the daily returns of the banking securities. Follow these steps to create the heat map:

1. Select the close column and then call the unstack method.

close_prices = history['close'].unstack(level=0)

2. Call the pct_change method.

daily_returns = close_prices.pct_change()

3. Call the corr method.

corr_matrix = daily_returns.corr()

4. Call the imshow method with the correlation matrix, a color map, and an interpolation method.

plt.imshow(corr_matrix, cmap='hot', interpolation='nearest')

5. In the same cell that you called the imshow method, call the title , xticks , and yticks , methods with a title and the axis tick labels.

plt.title('Banking Stocks and Bank Sector ETF Correlation Heat Map')
plt.xticks(np.arange(len(tickers)), labels=tickers)
plt.yticks(np.arange(len(tickers)), labels=tickers)

6. In the same cell that you called the imshow method, call the colorbar method.

plt.colorbar();

The Jupyter Notebook displays the heat map.

Create Pie Chart

You must import the plotting libraries and get some historical data to create pie charts.

In this example, you create a pie chart that shows the weights of the banking securities in a portfolio if you allocate to them based on their inverse volatility. Follow these steps to create the pie chart:

1. Select the close column and then call the unstack method.

close_prices = history['close'].unstack(level=0)

2. Call the pct_change method.

daily_returns = close_prices.pct_change()

3. Call the var method and then take the inverse.

inverse_variance = 1 / daily_returns.var()

4. Call the pie method with the inverse_variance Series , the plot labels, and a display format.

plt.pie(inverse_variance, labels=inverse_variance.index, autopct='%1.1f%%')

5. In the cell that you called the pie method, call the title method with a title.

plt.title('Banking Stocks and Bank Sector ETF Allocation');

The Jupyter Notebook displays the pie chart.

Charting > Plotly

Introduction

plotly is an online charting tool with a python API. It offers the ability to create rich and interactive graphs.

Import Libraries

Import the plotly library.

import plotly.express as px
import plotly.graph_objects as go

Get Historical Data

Get some historical market data to produce the plots. For example, to get data for a bank sector ETF and some banking companies over 2021, run:

qb = QuantBook()
tickers = ["XLF",   # Financial Select Sector SPDR Fund
           "COF",   # Capital One Financial Corporation
           "GS",    # Goldman Sachs Group, Inc.
           "JPM",   # J P Morgan Chase & Co
           "WFC"]   # Wells Fargo & Company   
symbols = [qb.AddEquity(ticker, Resolution.Daily).Symbol for ticker in tickers]
history = qb.History(symbols, datetime(2021, 1, 1), datetime(2022, 1, 1))

Create Candlestick Chart

You must import the plotting libraries and get some historical data to create candlestick charts.

In this example, you create a candlestick chart that shows the open, high, low, and close prices of one of the banking securities. Follow these steps to create the candlestick chart:

1. Select a Symbol .

symbol = symbols[0]

2. Slice the history DataFrame with the symbol .

data = history.loc[symbol]

3. Call the Candlestick constructor with the time and open, high, low, and close price Series .

candlestick = go.Candlestick(x=data.index,
                             open=data['open'],
                             high=data['high'],
                             low=data['low'],
                             close=data['close'])

4. Call the Layout constructor with a title and axes labels.
   

layout = go.Layout(title=go.layout.Title(text=f'{symbol.Value} OHLC'),
                   xaxis_title='Date',
                   yaxis_title='Price',
                   xaxis_rangeslider_visible=False)

5. Call the Figure constructor with the candlestick and layout .

fig = go.Figure(data=[candlestick], layout=layout)

6. Call the show method.
   

fig.show()

The Jupyter Notebook displays the candlestick chart.

Create Line Chart

You must import the plotting libraries and get some historical data to create line charts.

In this example, you create a line chart that shows the closing price for one of the banking securities. Follow these steps to create the line chart:

1. Select a Symbol .

symbol = symbols[0]

2. Slice the history DataFrame with the symbol and then select the close column.

data = history.loc[symbol]['close']

3. Call the DataFrame constructor with the data Series and then call the reset_index method.

data = pd.DataFrame(data).reset_index()

4. Call the line method with data , the column names of the x- and y-axis in data , and the plot title.

fig = px.line(data, x='time', y='close', title=f'{symbol} Close price')

5. Call the show method.

fig.show()

The Jupyter Notebook displays the line chart.

Create Scatter Plot

You must import the plotting libraries and get some historical data to create scatter plots.

In this example, you create a scatter plot that shows the relationship between the daily returns of two banking securities. Follow these steps to create the scatter plot:

1. Select 2 Symbol s.

For example, to select the Symbol s of the first 2 bank stocks, run:

symbol1 = symbols[1]
symbol2 = symbols[2]

2. Slice the history DataFrame with each Symbol and then select the close column.

close_price1 = history.loc[symbol1]['close']
close_price2 = history.loc[symbol2]['close']

3. Call the pct_change and dropna methods on each Series .

daily_return1 = close_price1.pct_change().dropna()
daily_return2 = close_price2.pct_change().dropna()

4. Call the scatter method with the 2 return Series , the trendline option, and axes labels.

fig = px.scatter(x=daily_return1, y=daily_return2, trendline='ols', 
                 labels={'x': symbol1.Value, 'y': symbol2.Value}) 

5. Call the update_layout method with a title.

fig.update_layout(title=f'{symbol1.Value} vs {symbol2.Value} Daily % Returns');

6. Call the show method.

fig.show()

The Jupyter Notebook displays the scatter plot.

Create Histogram

You must import the plotting libraries and get some historical data to create histograms.

In this example, you create a histogram that shows the distribution of the daily percent returns of the bank sector ETF. Follow these steps to create the histogram:

1. Select the Symbol .

symbol = symbols[0]

2. Slice the history DataFrame with the symbol and then select the close column.

data = history.loc[symbol]['close']

3. Call the pct_change method and then call the dropna method.

daily_returns = data.pct_change().dropna()

4. Call the DataFrame constructor with the data Series and then call the reset_index method.

daily_returns = pd.DataFrame(daily_returns).reset_index()

5. Call the histogram method with the daily_returns DataFrame, the x-axis label, a title, and the number of bins.

fig = px.histogram(daily_returns, x='close', 
                   title=f'{symbol} Daily Return of Close Price Distribution', 
                   nbins=20)

6. Call the show method.

fig.show()

The Jupyter Notebook displays the histogram.

Create Bar Chart

You must import the plotting libraries and get some historical data to create bar charts.

In this example, you create a bar chart that shows the average daily percent return of the banking securities. Follow these steps to create the bar chart:

1. Select the close column and then call the unstack method.
   

close_prices = history['close'].unstack(level=0)

2. Call the pct_change method and then multiply by 100.

daily_returns = close_prices.pct_change() * 100

3. Call the mean method.

avg_daily_returns = daily_returns.mean()

4. Call the DataFrame constructor with the avg_daily_returns Series and then call the reset_index method.

avg_daily_returns = pd.DataFrame(avg_daily_returns, columns=["avg_daily_ret"]).reset_index()

5. Call the bar method with the avg_daily_returns and the axes column names.

fig = px.bar(avg_daily_returns, x='symbol', y='avg_daily_ret')

6. Call the update_layout method with a title.

fig.update_layout(title='Banking Stocks Average Daily % Returns');

7. Call the show method.

fig.show()

The Jupyter Notebook displays the bar plot.

Create Heat Map

You must import the plotting libraries and get some historical data to create heat maps.

In this example, you create a heat map that shows the correlation between the daily returns of the banking securities. Follow these steps to create the heat map:

1. Select the close column and then call the unstack method.

close_prices = history['close'].unstack(level=0)

2. Call the pct_change method.

daily_returns = close_prices.pct_change()

3. Call the corr method.

corr_matrix = daily_returns.corr()

4. Call the imshow method with the corr_matrix and the axes labels.

fig = px.imshow(corr_matrix, x=tickers, y=tickers)

5. Call the update_layout method with a title.

fig.update_layout(title='Banking Stocks and bank sector ETF Correlation Heat Map');

6. Call the show method.

fig.show()

The Jupyter Notebook displays the heat map.

Create Pie Chart

You must import the plotting libraries and get some historical data to create pie charts.

In this example, you create a pie chart that shows the weights of the banking securities in a portfolio if you allocate to them based on their inverse volatility. Follow these steps to create the pie chart:

1. Select the close column and then call the unstack method.

close_prices = history['close'].unstack(level=0)

2. Call the pct_change method.

daily_returns = close_prices.pct_change()

3. Call the var method and then take the inverse.

inverse_variance = 1 / daily_returns.var()

4. Call the DataFrame constructor with the inverse_variance Series and then call the reset_index method.
   

inverse_variance = pd.DataFrame(inverse_variance, columns=["inverse variance"]).reset_index()

5. Call the pie method with the inverse_variance DataFrame , the column name of the values, and the column name of the names.

fig = px.pie(inverse_variance, values='inverse variance', names='symbol')

6. Call the update_layout method with a title.

fig.update_layout(title='Asset Allocation of bank stocks and bank sector ETF');

7. Call the show method.

fig.show()

The Jupyter Notebook displays the pie chart.

Charting > Seaborn

Introduction

seaborn is a data visualization library based on matplotlib . It makes it easier to create more complicated plots and allows us to create much more visually-appealing charts than matplotlib charts.

Import Libraries

Follow these steps to import the libraries that you need:

1. Import the seaborn and matplotlib libraries.

import seaborn as sns
import matplotlib.pyplot as plt

2. Import, and then call, the register_matplotlib_converters method.

from pandas.plotting import register_matplotlib_converters
register_matplotlib_converters()

Get Historical Data

Get some historical market data to produce the plots. For example, to get data for a bank sector ETF and some banking companies over 2021, run:

qb = QuantBook()
tickers = ["XLF",   # Financial Select Sector SPDR Fund
           "COF",   # Capital One Financial Corporation
           "GS",    # Goldman Sachs Group, Inc.
           "JPM",   # J P Morgan Chase & Co
           "WFC"]   # Wells Fargo & Company   
symbols = [qb.AddEquity(ticker, Resolution.Daily).Symbol for ticker in tickers]
history = qb.History(symbols, datetime(2021, 1, 1), datetime(2022, 1, 1))

Create Candlestick Chart

Seaborn does not currently support candlestick charts. Use one of the other plotting libraries to create candlestick charts.

Create Line Chart

You must import the plotting libraries and get some historical data to create line charts.

In this example, you create a line chart that shows the closing price for one of the banking securities. Follow these steps to create the chart:

1. Select a Symbol .

symbol = symbols[0]

2. Slice the history DataFrame with the symbol and then select the close column.

data = history.loc[symbol]['close']

3. Call the DataFrame constructor with the data Series and then call the reset_index method.

data = pd.DataFrame(data).reset_index()

4. Call the lineplot method with the data Series and the column name of each axis.

plot = sns.lineplot(data=data,
                    x='time', 
                    y='close')

5. In the same cell that you called the lineplot method, call the set method with the y-axis label and a title.

plot.set(ylabel="price", title=f"{symbol} Price Over Time");

The Jupyter Notebook displays the line chart.

Create Scatter Plot

You must import the plotting libraries and get some historical data to create scatter plots.

In this example, you create a scatter plot that shows the relationship between the daily returns of two banking securities. Follow these steps to create the scatter plot:

1. Select 2 Symbol s.

For example, to select the Symbol s of the first 2 bank stocks, run:

symbol1 = symbols[1]
symbol2 = symbols[2]

2. Select the close column of the history DataFrame, call the unstack method, and then select the symbol1 and symbol2 columns.

close_prices = history['close'].unstack(0)[[symbol1, symbol2]]

3. Call the pct_change method and then call the dropna method.

daily_returns = close_prices.pct_change().dropna()

4. Call the regplot method with the daily_returns DataFrame and the column names.

plot = sns.regplot(data=daily_returns, 
                   x=daily_returns.columns[0], 
                   y=daily_returns.columns[1])

5. In the same cell that you called the regplot method, call the set method with the axis labels and a title.

plot.set(xlabel=f'{daily_returns.columns[0]} % Returns', 
         ylabel=f'{daily_returns.columns[1]} % Returns', 
         title=f'{symbol1} vs {symbol2} Daily % Returns');

The Jupyter Notebook displays the scatter plot.

Create Histogram

You must import the plotting libraries and get some historical data to create histograms.

In this example, you create a histogram that shows the distribution of the daily percent returns of the bank sector ETF. Follow these steps to create the histogram:

1. Select the Symbol .

symbol = symbols[0]

2. Slice the history DataFrame with the symbol and then select the close column.

data = history.loc[symbol]['close']

3. Call the pct_change method and then call the dropna method.

daily_returns = data.pct_change().dropna()

4. Call the DataFrame constructor with the daily_returns Series and then call the reset_index method.

daily_returns = pd.DataFrame(daily_returns).reset_index()

5. Call the histplot method with the daily_returns , the close column name, and the number of bins.

plot = sns.histplot(daily_returns, x='close', bins=20)

6. In the same cell that you called the histplot method, call the set method with the axis labels and a title.

plot.set(xlabel='Return', 
         ylabel='Frequency', 
         title=f'{symbol} Daily Return of Close Price Distribution');

The Jupyter Notebook displays the histogram.

Create Bar Chart

You must import the plotting libraries and get some historical data to create bar charts.

In this example, you create a bar chart that shows the average daily percent return of the banking securities. Follow these steps to create the bar chart:

1. Select the close column and then call the unstack method.

close_prices = history['close'].unstack(level=0)

2. Call the pct_change method and then multiply by 100.

daily_returns = close_prices.pct_change() * 100

3. Call the mean method.

avg_daily_returns = daily_returns.mean()

4. Call the DataFrame constructor with the avg_daily_returns Series and then call the reset_index method.

avg_daily_returns = pd.DataFrame(avg_daily_returns, columns=["avg_daily_ret"]).reset_index()

5. Call barplot method with the avg_daily_returns Series and the axes column names.

plot = sns.barplot(data=avg_daily_returns, x='symbol', y='avg_daily_ret')

6. In the same cell that you called the barplot method, call the set method with the axis labels and a title.

plot.set(xlabel='Tickers', 
         ylabel='%', 
         title='Banking Stocks Average Daily % Returns')

7. In the same cell that you called the set method, call the tick_params method to rotate the x-axis labels.

plot.tick_params(axis='x', rotation=90)

The Jupyter Notebook displays the bar chart.

Create Heat Map

You must import the plotting libraries and get some historical data to create heat maps.

In this example, you create a heat map that shows the correlation between the daily returns of the banking securities. Follow these steps to create the heat map:

1. Select the close column and then call the unstack method.

close_prices = history['close'].unstack(level=0)

2. Call the pct_change method.

daily_returns = close_prices.pct_change()

3. Call the corr method.

corr_matrix = daily_returns.corr()

4. Call the heatmap method with the corr_matrix and the annotation argument enabled.

plot = sns.heatmap(corr_matrix, annot=True)

5. In the same cell that you called the heatmap method, call the set method with a title.

plot.set(title='Bank Stocks and Bank Sector ETF Correlation Coefficients');

The Jupyter Notebook displays the heat map.

Create Pie Chart

You must import the plotting libraries and get some historical data to create pie charts.

In this example, you create a pie chart that shows the weights of the banking securities in a portfolio if you allocate to them based on their inverse volatility. Follow these steps to create the pie chart:

1. Select the close column and then call the unstack method.

close_prices = history['close'].unstack(level=0)

2. Call the pct_change method.

daily_returns = close_prices.pct_change()

3. Call var method and then take the inverse.

inverse_variance = 1 / daily_returns.var()

4. Call the color_palette method with a palette name and then truncate the returned colors to so that you have one color for each security.

colors = sns.color_palette('pastel')[:len(inverse_variance.index)]

5. Call the pie method with the security weights, labels, and colors.

plt.pie(inverse_variance, labels=inverse_variance.index, colors=colors, autopct='%1.1f%%')

6. In the same cell that you called the pie method, call the title method with a title.

plt.title(title='Banking Stocks and Bank Sector ETF Allocation');

The Jupyter Notebook displays the pie chart.

Charting > Plotly NET

Introduction

Plotly.NET provides functions for generating and rendering plotly.js charts in .NET programming languages. Our .NET interactive notebooks support its C# implementation.

Import Libraries

Follow these steps to import the libraries that you need:

1. Load the necessary assembly files.

#r "../Plotly.NET.dll"

2. Import the Plotly.NET and Plotly.NET.LayoutObjects packages.

using Plotly.NET;
using Plotly.NET.LayoutObjects;

Get Historical Data

Get some historical market data to produce the plots. For example, to get data for a bank sector ETF and some banking companies over 2021, run:

var qb = new QuantBook();
var tickers = new[] 
{
    "XLF",  // Financial Select Sector SPDR Fund
    "COF",  // Capital One Financial Corporation
    "GS",   // Goldman Sachs Group, Inc.
    "JPM",  // J P Morgan Chase & Co
    "WFC"   // Wells Fargo & Company   
}
var symbols = tickers.Select(ticker => qb.AddEquity(ticker, Resolution.Daily).Symbol);
var history = qb.History(symbols, new DateTime(2021, 1, 1), new DateTime(2022, 1, 1));

Create Candlestick Chart

You must import the plotting libraries and get some historical data to create candlestick charts.

In this example, you create a candlestick chart that shows the open, high, low, and close prices of one of the banking securities. Follow these steps to create the candlestick chart:

1. Select a Symbol .

var symbol = symbols.First();

2. Call the Chart2D.Chart.Candlestick constructor with the time and open, high, low, and close price IEnumerable .

var bars = history.Select(slice => slice.Bars[symbol]);
var chart = Chart2D.Chart.Candlestick<decimal, decimal, decimal, decimal, DateTime, string>(
    bars.Select(x => x.Open),
    bars.Select(x => x.High),
    bars.Select(x => x.Low),
    bars.Select(x => x.Close),
    bars.Select(x => x.EndTime)
);

3. Call the Layout constructor and set the title , xaxis , and yaxis properties as the title and axes label objects.
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Price ($)");
Title title = Title.init($"{symbol} OHLC");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

4. Assign the Layout to the chart.
   

chart.WithLayout(layout);

5. Show the plot.
   

HTML(GenericChart.toChartHTML(chart));

The Jupyter Notebook displays the candlestick chart.

Create Line Chart

You must import the plotting libraries and get some historical data to create line charts.

In this example, you create a line chart that shows the volume of a security. Follow these steps to create the chart:

1. Select a Symbol .

var symbol = symbols.First();

2. Call the Chart2D.Chart.Line constructor with the timestamps and volumes.

var bars = history.Select(slice => slice.Bars[symbol]);
var chart = Chart2D.Chart.Line<DateTime, decimal, string>(
    bars.Select(x => x.EndTime),
    bars.Select(x => x.Volume)
);

3. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "Volume");
Title title = Title.init($"{symbol} Volume");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

4. Assign the Layout to the chart.
   

chart.WithLayout(layout);

5. Show the plot.

HTML(GenericChart.toChartHTML(chart));

The Jupyter Notebook displays the line chart.

Create Scatter Plot

You must import the plotting libraries and get some historical data to create scatter plots.

In this example, you create a scatter plot that shows the relationship between the daily price of two securities. Follow these steps to create the scatter plot:

1. Select two Symbol objects.

var symbol1 = symbols.First();
var symbol2 = symbols.Last();

2. Call the Chart2D.Chart.Point constructor with the closing prices of both securities.

var chart = Chart2D.Chart.Point<decimal, decimal, string>(
    history.Select(slice => slice.Bars[symbol1].Close),
    history.Select(slice => slice.Bars[symbol2].Close)
);

3. Create a Layout .
   

LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", $"{symbol1} Price ($)");
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", $"{symbol2} Price ($)");
Title title = Title.init($"{symbol1} vs {symbol2}");

Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("title", title);

4. Assign the Layout to the chart.
   

chart.WithLayout(layout);

5. Show the plot.

HTML(GenericChart.toChartHTML(chart));

The Jupyter Notebook displays the scatter plot.

Indicators

Indicators > Data Point Indicators

Introduction

This page explains how to create, update, and visualize LEAN data-point indicators.

Create Subscriptions

You need to subscribe to some market data in order to calculate indicator values.

var qb = new QuantBook();
var symbol = qb.AddEquity("SPY").Symbol;

qb = QuantBook()
symbol = qb.AddEquity("SPY").Symbol

Create Indicator Timeseries

You need to subscribe to some market data and create an indicator in order to calculate a timeseries of indicator values. In this example, use a 20-period 2-standard-deviation BollingerBands indicator.

var bb = new BollingerBands(20, 2);

bb = BollingerBands(20, 2)

You can create the indicator timeseries with the Indicator helper method or you can manually create the timeseries.

Indicator Helper Method

To create an indicator timeseries with the helper method, call the Indicator method.

var bbIndicator = qb.Indicator(bb, symbol, 50, Resolution.Daily);

bb_dataframe = qb.Indicator(bb, symbol, 50, Resolution.Daily)

Manually Create the Indicator Timeseries

Follow these steps to manually create the indicator timeseries:

1. Get some historical data .

var history = qb.History(symbol, 70, Resolution.Daily);

history = qb.History[TradeBar](symbol, 70, Resolution.Daily)

2. Create a RollingWindow for each attribute of the indicator to hold their values.

var time = new RollingWindow<DateTime>(50);
var window = new Dictionary<string, RollingWindow<decimal>>();
window["bollingerbands"] = new RollingWindow<decimal>(50);
window["lowerband"] = new RollingWindow<decimal>(50);
window["middleband"] = new RollingWindow<decimal>(50);
window["upperband"] = new RollingWindow<decimal>(50);
window["bandwidth"] = new RollingWindow<decimal>(50);
window["percentb"] = new RollingWindow<decimal>(50);
window["standarddeviation"] = new RollingWindow<decimal>(50);
window["price"] = new RollingWindow<decimal>(50);

window = {}
window['time'] = RollingWindow[DateTime](50)
window["bollingerbands"] = RollingWindow[float](50)
window["lowerband"] = RollingWindow[float](50)
window["middleband"] = RollingWindow[float](50)
window["upperband"] = RollingWindow[float](50)
window["bandwidth"] = RollingWindow[float](50)
window["percentb"] = RollingWindow[float](50)
window["standarddeviation"] = RollingWindow[float](50)
window["price"] = RollingWindow[float](50)

3. Attach a handler method to the indicator that updates the RollingWindow objects.

bb.Updated += (sender, updated) => 
{
    var indicator = (BollingerBands)sender;
    time.Add(updated.EndTime);
    window["bollingerbands"].Add(updated);
    window["lowerband"].Add(indicator.LowerBand);
    window["middleband"].Add(indicator.MiddleBand);
    window["upperband"].Add(indicator.UpperBand);
    window["bandwidth"].Add(indicator.BandWidth);
    window["percentb"].Add(indicator.PercentB);
    window["standarddeviation"].Add(indicator.StandardDeviation);
    window["price"].Add(indicator.Price);
};

def UpdateBollingerBandWindow(sender: object, updated: IndicatorDataPoint) -> None:
    indicator = sender
    window['time'].Add(updated.EndTime)
    window["bollingerbands"].Add(updated.Value)
    window["lowerband"].Add(indicator.LowerBand.Current.Value)
    window["middleband"].Add(indicator.MiddleBand.Current.Value)
    window["upperband"].Add(indicator.UpperBand.Current.Value)
    window["bandwidth"].Add(indicator.BandWidth.Current.Value)
    window["percentb"].Add(indicator.PercentB.Current.Value)
    window["standarddeviation"].Add(indicator.StandardDeviation.Current.Value)
    window["price"].Add(indicator.Price.Current.Value)

bb.Updated += UpdateBollingerBandWindow

When the indicator receives new data, the preceding handler method adds the new IndicatorDataPoint values into the respective RollingWindow .

4. Iterate through the historical market data and update the indicator.

foreach(var bar in history)
{
    bb.Update(bar.EndTime, bar.Close);
}

for bar in history:
    bb.Update(bar.EndTime, bar.Close)

5. Display the data.

Console.WriteLine($"time,{string.Join(',', window.Select(kvp => kvp.Key))}");
foreach (var i in Enumerable.Range(0, 5).Reverse())
{
    var data = string.Join(", ", window.Select(kvp => Math.Round(kvp.Value[i],6)));
    Console.WriteLine($"{time[i]:yyyyMMdd}, {data}");
}


6. Populate a DataFrame with the data in the RollingWindow objects.

bb_dataframe = pd.DataFrame(window).set_index('time')

Plot Indicators

Jupyter Notebooks don't currently support libraries to plot historical data, but we are working on adding the functionality. Until the functionality is added, use Python to plot data point indicators.

You need to create an indicator timeseries to plot the indicator values.

Follow these steps to plot the indicator values:

1. Select the columns/features to plot.

bb_plot = bb_indicator[["upperband", "middleband", "lowerband", "price"]]

2. Call the plot method.

bb_plot.plot(figsize=(15, 10), title="SPY BB(20,2)"))

3. Show the plots.

plt.show()

Indicators > Bar Indicators

Introduction

This page explains how to create, update, and visualize LEAN bar indicators.

Create Subscriptions

You need to subscribe to some market data in order to calculate indicator values.

var qb = new QuantBook();
var symbol = qb.AddEquity("SPY").Symbol;

qb = QuantBook()
symbol = qb.AddEquity("SPY").Symbol

Create Indicator Timeseries

You need to subscribe to some market data and create an indicator in order to calculate a timeseries of indicator values. In this example, use a 20-period AverageTrueRange indicator.

var atr = new AverageTrueRange(20);

atr = AverageTrueRange(20)

You can create the indicator timeseries with the Indicator helper method or you can manually create the timeseries.

Indicator Helper Method

To create an indicator timeseries with the helper method, call the Indicator method.

var atrIndicator = qb.Indicator(atr, symbol, 50, Resolution.Daily);

atr_dataframe = qb.Indicator(atr, symbol, 50, Resolution.Daily)

Manually Create the Indicator Timeseries

Follow these steps to manually create the indicator timeseries:

1. Get some historical data .

var history = qb.History(symbol, 70, Resolution.Daily);

history = qb.History[TradeBar](symbol, 70, Resolution.Daily)

2. Create a RollingWindow for each attribute of the indicator to hold their values.

var time = new RollingWindow<DateTime>(50);
var window = new Dictionary<string, RollingWindow<decimal>>();
window["averagetruerange"] = new RollingWindow<decimal>(50);
window["truerange"] = new RollingWindow<decimal>(50);

window = {}
window['time'] = RollingWindow[DateTime](50)
window['averagetruerange'] = RollingWindow[float](50)
window["truerange"] = RollingWindow[float](50)

3. Attach a handler method to the indicator that updates the RollingWindow objects.

atr.Updated += (sender, updated) => 
{
    var indicator = (AverageTrueRange)sender;
    time.Add(updated.EndTime);
    window["averagetruerange"].Add(updated);
    window["truerange"].Add(indicator.TrueRange);
};

def UpdateAverageTrueRangeWindow(sender: object, updated: IndicatorDataPoint) -> None:
    indicator = sender
    window['time'].Add(updated.EndTime)
    window["averagetruerange"].Add(updated.Value)
    window["truerange"].Add(indicator.TrueRange.Current.Value)

atr.Updated += UpdateAverageTrueRangeWindow

When the indicator receives new data, the preceding handler method adds the new IndicatorDataPoint values into the respective RollingWindow .

4. Iterate through the historical market data and update the indicator.

foreach(var bar in history){
    // Update the indicators with the whole bar.
    atr.Update(bar);
}

for bar in history:
    atr.Update(bar)

5. Display the data.

Console.WriteLine($"time,{string.Join(',', window.Select(kvp => kvp.Key))}");
foreach (var i in Enumerable.Range(0, 5).Reverse())
{
    var data = string.Join(", ", window.Select(kvp => Math.Round(kvp.Value[i],6)));
    Console.WriteLine($"{time[i]:yyyyMMdd}, {data}");
}


6. Populate a DataFrame with the data in the RollingWindow objects.

atr_dataframe = pd.DataFrame(window).set_index('time')

Plot Indicators

Jupyter Notebooks don't currently support libraries to plot historical data, but we are working on adding the functionality. Until the functionality is added, use Python to plot bar indicators.

You need to create an indicator timeseries to plot the indicator values.

Follow these steps to plot the indicator values:

1. Call the plot method.

atr_indicator.plot(title="SPY ATR(20)", figsize=(15, 10))

2. Show the plots.

plt.show()

Indicators > Trade Bar Indicators

Introduction

This page explains how to create, update, and visualize LEAN TradeBar indicators.

Create Subscriptions

You need to subscribe to some market data in order to calculate indicator values.

var qb = new QuantBook();
var symbol = qb.AddEquity("SPY").Symbol;

qb = QuantBook()
symbol = qb.AddEquity("SPY").Symbol

Create Indicator Timeseries

You need to subscribe to some market data and create an indicator in order to calculate a timeseries of indicator values. In this example, use a 20-period VolumeWeightedAveragePriceIndicator indicator.

var vwap = new VolumeWeightedAveragePriceIndicator(20);

vwap = VolumeWeightedAveragePriceIndicator(20)

You can create the indicator timeseries with the Indicator helper method or you can manually create the timeseries.

Indicator Helper Method

To create an indicator timeseries with the helper method, call the Indicator method.

var vwapIndicator = qb.Indicator(vwap, symbol, 50, Resolution.Daily);

vwap_dataframe = qb.Indicator(vwap, symbol, 50, Resolution.Daily)

Manually Create the Indicator Timeseries

Follow these steps to create an indicator timeseries:

1. Get some historical data .

var history = qb.History(symbol, 70, Resolution.Daily);

history = qb.History[TradeBar](symbol, 70, Resolution.Daily)

2. Create a RollingWindow for each attribute of the indicator to hold their values.

var time = new RollingWindow<DateTime>(50);
var window = new Dictionary<string, RollingWindow<decimal>>();
window["volumeweightedaveragepriceindicator"] = new RollingWindow<decimal>(50);

window = {}
window['time'] = RollingWindow[DateTime](50)
window['volumeweightedaveragepriceindicator'] = RollingWindow[float](50)

3. Attach a handler method to the indicator that updates the RollingWindow objects.

vwap.Updated += (sender, updated) => 
{
    time.Add(updated.EndTime);
    window["volumeweightedaveragepriceindicator"].Add(updated);
};

def UpdateVWAPWindow(sender: object, updated: IndicatorDataPoint) -> None:
    window['time'].Add(updated.EndTime)
    window["volumeweightedaveragepriceindicator"].Add(updated.Value)

vwap.Updated += UpdateVWAPWindow

When the indicator receives new data, the preceding handler method adds the new IndicatorDataPoint values into the respective RollingWindow .

4. Iterate through the historical market data and update the indicator.

foreach(var bar in history){
    // Update the indicators with the whole TradeBar.
    vwap.Update(bar);
}

for bar in history:
    vwap.Update(bar)

5. Display the data.

Console.WriteLine($"time,{string.Join(',', window.Select(kvp => kvp.Key))}");
foreach (var i in Enumerable.Range(0, 5).Reverse())
{
    var data = string.Join(", ", window.Select(kvp => Math.Round(kvp.Value[i],6)));
    Console.WriteLine($"{time[i]:yyyyMMdd}, {data}");
}


6. Populate a DataFrame with the data in the RollingWindow objects.

vwap_dataframe = pd.DataFrame(window).set_index('time')

Plot Indicators

Jupyter Notebooks don't currently support libraries to plot historical data, but we are working on adding the functionality. Until the functionality is added, use Python to plot TradeBar indicators.

Follow these steps to plot the indicator values:

1. Call the plot method.

vwap_indicator.plot(title="SPY VWAP(20)", figsize=(15, 10))

2. Show the plots.

plt.show()

Indicators > Combining Indicators

Introduction

This page explains how to create, update, and visualize LEAN Composite indicators.

Create Subscriptions

You need to subscribe to some market data in order to calculate indicator values.

var qb = new QuantBook();
var symbol = qb.AddEquity("SPY").Symbol;

qb = QuantBook()
symbol = qb.AddEquity("SPY").Symbol

Create Indicator Timeseries

You need to subscribe to some market data and create a composite indicator in order to calculate a timeseries of indicator values. In this example, use a 10-period SimpleMovingAverage of a 10-period RelativeStrengthIndex indicator.

var rsi = new RelativeStrengthIndex(10);
var sma = new SimpleMovingAverage(10);
var smaOfRsi = IndicatorExtensions.Of(sma, rsi);

rsi = RelativeStrengthIndex(10)
sma = SimpleMovingAverage(10)
sma_of_rsi = IndicatorExtensions.Of(sma, rsi)

Follow these steps to create an indicator timeseries:

1. Get some historical data .

var history = qb.History(symbol, 70, Resolution.Daily);

history = qb.History[TradeBar](symbol, 70, Resolution.Daily)

2. Create a RollingWindow for each attribute of the indicator to hold their values.

In this example, save 50 data points.

var time = new RollingWindow<DateTime>(50);
var window = new Dictionary<string, RollingWindow<decimal>>();
window["SMA Of RSI"] = new RollingWindow<decimal>(50);
window["rollingsum"] = new RollingWindow<decimal>(50);

window = {}
window['time'] = RollingWindow[DateTime](50)
window["SMA Of RSI"] = RollingWindow[float](50)
window["rollingsum"] = RollingWindow[float](50)(50)

3. Attach a handler method to the indicator that updates the RollingWindow objects.

smaOfRsi.Updated += (sender, updated) => 
{
    var indicator = (SimpleMovingAverage)sender;    // Use terminal indicator class.
    time.Add(updated.EndTime);
    window["SMA Of RSI"].Add(updated);
    window["rollingsum"].Add(indicator.RollingSum);
};

def UpdateSmaOfRsiWindow(sender: object, updated: IndicatorDataPoint) -> None:
    indicator = sender
    window['time'].Add(updated.EndTime)
    window["SMA Of RSI"].Add(updated.Value)
    window["rollingsum"].Add(indicator.RollingSum.Current.Value)

sma_of_rsi.Updated += UpdateSmaOfRsiWindow

When the indicator receives new data, the preceding handler method adds the new IndicatorDataPoint values into the respective RollingWindow .

4. Iterate the historical market data to update the indicators and the RollingWindow s.

foreach(var bar in history){
    // Update the base indicators, the composite indicator will update automatically when the base indicator is updated.
    rsi.Update(bar.EndTime, bar.Close);
}

for bar in history:
    rsi.Update(bar.EndTime, bar.Close)

5. Display the data.

Console.WriteLine($"time,{string.Join(',', window.Select(kvp => kvp.Key))}");
foreach (var i in Enumerable.Range(0, 5).Reverse())
{
    var data = string.Join(", ", window.Select(kvp => Math.Round(kvp.Value[i],6)));
    Console.WriteLine($"{time[i]:yyyyMMdd}, {data}");
}


6. Populate a DataFrame with the data in the RollingWindow objects.

sma_of_rsi_dataframe = pd.DataFrame(window).set_index('time')

Plot Indicators

Jupyter Notebooks don't currently support libraries to plot historical data, but we are working on adding the functionality. Until the functionality is added, use Python to plot composite indicators.

Follow these steps to plot the indicator values:

1. Select the columns/features to plot.

sma_of_rsi_plot = sma_of_rsi_dataframe[["SMA Of RSI"]]

2. Call the plot method.

sma_of_rsi_plot.plot(title="SPY SMA(10) of RSI(10)", figsize=(15, 10))

3. Show the plots.

plt.show()

Indicators > Custom Indicators

Introduction

This page explains how to create and update custom indicators.

Create Subscriptions

You need to subscribe to some market data in order to calculate indicator values.

var qb = new QuantBook();
var symbol = qb.AddEquity("SPY").Symbol;

qb = QuantBook()
symbol = qb.AddEquity("SPY").Symbol

Create Indicator Timeseries

You need to subscribe to some market data in order to calculate a timeseries of indicator values.

Follow these steps to create an indicator timeseries:

1. Get some historical data .

var history = qb.History(symbol, 70, Resolution.Daily);

history = qb.History[TradeBar](symbol, 70, Resolution.Daily)

2. Define a custom indicator class that inherits from the Indicator superclass.
3. Define a custom indicator class. Note the PythonIndicator superclass inheritance, Value attribute, and Update method are mandatory.

In this tutorial, create an ExpectedShortfallPercent indicator that uses Monte Carlo to calculate the expected shortfall of returns. Use the WindowIndicator superclass instead of Indicator for using a period of historical data stored in a RollingWindow .

In this tutorial, create an ExpectedShortfallPercent indicator that uses Monte Carlo to calculate the expected shortfall of returns.

public class ExpectedShortfallPercent : WindowIndicator<IndicatorDataPoint>, IIndicatorWarmUpPeriodProvider
{
    private decimal _alpha;
    
    // Set up IndicatorDataPoint attributes for the indicator.
    public IndicatorBase<IndicatorDataPoint> ValueAtRisk { get; }

    // Set up the WarmUpPeriod attribute to provide implementation of the IIndicatorWarmUpPeriodProvider interface.
    public override int WarmUpPeriod => Period;

    // Set up the constructor.
    // period: The lookback period for return distribution.
    // alpha: Alpha level of VaR cutoff.
    public ExpectedShortfallPercent(int period, decimal alpha)
        : base("ES", period)
    {
        _alpha = alpha;
        ValueAtRisk = new Identity("ES_VaR");
    }

    // Override the IsReady method to set up the flag of the Indicator and its IndicatorDataPoint attributes are ready.
    public override bool IsReady => ValueAtRisk.IsReady;

    // Mandatory: Override the ComputeNextValue method to calculate the indictor value.
    protected override decimal ComputeNextValue(IReadOnlyWindow<IndicatorDataPoint> window, IndicatorDataPoint input)
    {
        if (Samples < 2)
            return 0m;
                
        var n = Math.Min(Period, Samples);
        var cutoff = (int) Math.Ceiling(n * _alpha);
        
        var samples = new List<decimal>();
        for (int i = 0; i < window.Count - 1; i++)
        {
            samples.Add( (window[i] - window[i+1]) / window[i+1] );
        }
        var lowest = samples.OrderBy(x => x).Take(cutoff);
        
        ValueAtRisk.Update(input.Time, lowest.Last());
        return lowest.Average();
    }
}

class ExpectedShortfallPercent(PythonIndicator):
    import math, numpy as np
    
    def __init__(self, period, alpha):
        self.Value = None   # Attribute represents the indicator value
        self.ValueAtRisk = None
        
        self.alpha = alpha
        
        self.window = RollingWindow[float](period)
    
    # Override the IsReady attribute to flag all attributes values are ready.
    @property
    def IsReady(self) -> bool:
        return self.Value and self.ValueAtRisk
    
    # Method to update the indicator values. Note that it only receives 1 IBaseData object (Tick, TradeBar, QuoteBar) argument.
    def Update(self, input: BaseData) -> bool:
        count = self.window.Count
        
        self.window.Add(input.Close)
        
        # Update the Value and other attributes as the indicator current value.
        if count >= 2:
            cutoff = math.ceil(self.alpha * count)
            
            ret = [ (self.window[i] - self.window[i+1]) / self.window[i+1] for i in range(count-1) ]
            lowest = sorted(ret)[:cutoff]
            
            self.Value = np.mean(lowest)
            self.ValueAtRisk = lowest[-1]
            
        # return a boolean to indicate IsReady.
        return count >= 2

4. Initialize a new instance of the custom indicator.

var es = new ExpectedShortfallPercent(50, 0.05m);

custom = ExpectedShortfallPercent(50, 0.05)

5. Create a RollingWindow for each attribute of the indicator to hold their values.

In this example, save 20 data points.

var time = new RollingWindow<DateTime>(20);
var window = new Dictionary<string, RollingWindow<decimal>>();
window["expectedshortfall"] = new RollingWindow<decimal>(20);
window["valueatrisk"] = new RollingWindow<decimal>(20);

window = {}
window['time'] = RollingWindow[DateTime](20)
window['expectedshortfall'] = RollingWindow[float](20)
window['valueatrisk'] = RollingWindow[float](20)

6. Attach a handler method to the indicator that updates the RollingWindow objects.

es.Updated += (sender, updated) =>
{
    var indicator = (ExpectedShortfallPercent) sender;
    time.Add(updated.EndTime);
    window["expectedshortfall"].Add(updated);
    window["valueatrisk"].Add(indicator.ValueAtRisk.Current);
};

When the indicator receives new data, the preceding handler method adds the new IndicatorDataPoint values into the respective RollingWindow .

7. Iterate through the historical market data and update the indicator.

foreach(var bar in history){
    es.Update(bar.EndTime, bar.Close);
}

for bar in history:
    custom.Update(bar)
    
    # The Updated event handler is not available for custom indicator in Python, RollingWindows are needed to be updated in here.
    if custom.IsReady:
        window['time'].Add(bar.EndTime)
        window['expectedshortfall'].Add(custom.Value)
        window['valueatrisk'].Add(custom.ValueAtRisk)

8. Display the data.

Console.WriteLine($"time,{string.Join(',', window.Select(kvp => kvp.Key))}");
foreach (var i in Enumerable.Range(0, 5).Reverse())
{
    var data = string.Join(", ", window.Select(kvp => Math.Round(kvp.Value[i],6)));
    Console.WriteLine($"{time[i]:yyyyMMdd}, {data}");
}


9. Populate a DataFrame with the data in the RollingWindow objects.

custom_dataframe = pd.DataFrame(window).set_index('time'))

Plot Indicators

Jupyter Notebooks don't currently support libraries to plot historical data, but we are working on adding the functionality. Until the functionality is added, use Python to plot custom indicators.

Follow these steps to plot the indicator values:

1. Call the plot method.

custom_dataframe.plot()

2. Show the plot.

plt.show()

Indicators > Custom Resolutions

Introduction

This page explains how to create and update indicators with data of a custom resolution.

Create Subscriptions

You need to subscribe to some market data in order to calculate indicator values.

var qb = new QuantBook();
var symbol = qb.AddEquity("SPY").Symbol;

qb = QuantBook()
symbol = qb.AddEquity("SPY").Symbol

Create Indicator Timeseries

You need to subscribe to some market data and create an indicator in order to calculate a timeseries of indicator values.

Follow these steps to create an indicator timeseries:

1. Get some historical data .

var history = qb.History(symbol, 70, Resolution.Daily);

history = qb.History[TradeBar](symbol, 70, Resolution.Daily)

2. Create a data-point indicator.

In this example, use a 20-period 2-standard-deviation BollingerBands indicator.

var bb = new BollingerBands(20, 2);

bb = BollingerBands(20, 2)

3. Create a RollingWindow for each attribute of the indicator to hold their values.

var time = new RollingWindow<DateTime>(50);
var window = new Dictionary<string, RollingWindow<decimal>>();
window["bollingerbands"] = new RollingWindow<decimal>(50);
window["lowerband"] = new RollingWindow<decimal>(50);
window["middleband"] = new RollingWindow<decimal>(50);
window["upperband"] = new RollingWindow<decimal>(50);
window["bandwidth"] = new RollingWindow<decimal>(50);
window["percentb"] = new RollingWindow<decimal>(50);
window["standarddeviation"] = new RollingWindow<decimal>(50);
window["price"] = new RollingWindow<decimal>(50);

window = {}
window['time'] = RollingWindow[DateTime](50)
window["bollingerbands"] = RollingWindow[float](50)
window["lowerband"] = RollingWindow[float](50)
window["middleband"] = RollingWindow[float](50)
window["upperband"] = RollingWindow[float](50)
window["bandwidth"] = RollingWindow[float](50)
window["percentb"] = RollingWindow[float](50)
window["standarddeviation"] = RollingWindow[float](50)
window["price"] = RollingWindow[float](50)

4. Attach a handler method to the indicator that updates the RollingWindow objects.

bb.Updated += (sender, updated) => 
{
    var indicator = (BollingerBands)sender;
    time.Add(updated.EndTime);
    window["bollingerbands"].Add(updated);
    window["lowerband"].Add(indicator.LowerBand);
    window["middleband"].Add(indicator.MiddleBand);
    window["upperband"].Add(indicator.UpperBand);
    window["bandwidth"].Add(indicator.BandWidth);
    window["percentb"].Add(indicator.PercentB);
    window["standarddeviation"].Add(indicator.StandardDeviation);
    window["price"].Add(indicator.Price);
};

def UpdateBollingerBandWindow(sender: object, updated: IndicatorDataPoint) -> None:
    indicator = sender
    window['time'].Add(updated.EndTime)
    window["bollingerbands"].Add(updated.Value)
    window["lowerband"].Add(indicator.LowerBand.Current.Value)
    window["middleband"].Add(indicator.MiddleBand.Current.Value)
    window["upperband"].Add(indicator.UpperBand.Current.Value)
    window["bandwidth"].Add(indicator.BandWidth.Current.Value)
    window["percentb"].Add(indicator.PercentB.Current.Value)
    window["standarddeviation"].Add(indicator.StandardDeviation.Current.Value)
    window["price"].Add(indicator.Price.Current.Value)

bb.Updated += UpdateBollingerBandWindow

When the indicator receives new data, the preceding handler method adds the new IndicatorDataPoint values into the respective RollingWindow .

5. Create a TradeBarConsolidator to consolidate data into the custom resolution.

var consolidator = new TradeBarConsolidator(TimeSpan.FromDays(7));

consolidator = TradeBarConsolidator(timedelta(days=7))

6. Attach a handler method to feed data into the consolidator and updates the indicator with the consolidated bars.

consolidator.DataConsolidated += (sender, consolidated) =>
{
    bb.Update(consolidated.EndTime, consolidated.Close);
};

consolidator.DataConsolidated += lambda sender, consolidated: bb.Update(consolidated.EndTime, consolidated.Close)

When the consolidator receives 7 days of data, the handler generates a 7-day TradeBar and update the indicator.

7. Iterate through the historical market data and update the indicator.

foreach(var bar in history)
{
    consolidator.Update(bar);
}

for bar in history:
    consolidator.Update(bar)

8. Display the data.

Console.WriteLine($"time,{string.Join(',', window.Select(kvp => kvp.Key))}");
foreach (var i in Enumerable.Range(0, 5).Reverse())
{
    var data = string.Join(", ", window.Select(kvp => Math.Round(kvp.Value[i],6)));
    Console.WriteLine($"{time[i]:yyyyMMdd}, {data}");
}


9. Populate a DataFrame with the data in the RollingWindow objects.

bb_dataframe = pd.DataFrame(window).set_index('time')

Plot Indicators

Jupyter Notebooks don't currently support libraries to plot historical data, but we are working on adding the functionality. Until the functionality is added, use Python to plot indicators.

Follow these steps to plot the indicator values:

1. Select the columsn to plot.

df = bb_dataframe[['lowerband', 'middleband', 'upperband', 'price']]

2. Call the plot method.

df.plot()

3. Show the plot.

plt.show()

Object Store

Introduction

The Object Store is a file system that you can use in your algorithms to save, read, and delete data. The Object Store is organization-specific, so you can save or read data from the same Object Store in all of your organization's projects. The Object Store works like a key-value storage system where you can store regular strings, JSON encoded strings, XML encoded strings, and bytes. You can access the data you store in the Object Store from backtests, the Research Environment, and live algorithms.

Get All Stored Data

To get all of the keys and values in the Object Store, iterate through the ObjectStore object.

foreach (var kvp in qb.ObjectStore)
{
    var key = kvp.Key;
    var value = kvp.Value;
}

for kvp in qb.ObjectStore:
    key = kvp.Key
    value = kvp.Value

To iterate through just the keys in the Object Store, iterate through the Keys property.

foreach (var key in qb.ObjectStore.Keys)
{
    continue;
}

for key in qb.ObjectStore.Keys:
    continue

Create Sample Data

You need some data to store data in the Object Store.

Follow these steps to create some sample data:

1. Create a dictionary.

var dictSample = new Dictionary<string, int> { {"One", 1}, {"Two", 2}, {"Three", 3} };

2. Create a string .

var stringSample = "My string";

string_sample = "My string"

3. Create a Bytes object.

var bytesSample = Encoding.UTF8.GetBytes("My String");

bytes_sample = str.encode("My String")

4. Convert the dictionary to an XML -formatted object.

var xmlSample = new XElement("sample",
    dictSample.Select(kvp => new XElement(kvp.Key, kvp.Value)));
Console.WriteLine(xmlSample.ToString());

Save Data

The Object Store saves objects under a key-value system. If you save objects in backtests, you can access them from the Research Environment.

If you run algorithms in QuantConnect Cloud, you need storage create permissions to save data in the Object Store.

If you don't have data to store, create some sample data .

You can save the following types of objects in the Object Store:

• Bytes objects
• string objects
• JSON objects
• XML-formatted objects

You can save Bytes and string objects in the Object Store.

Bytes

To save a Bytes object, call the SaveBytes method.

var saveSuccessful = qb.ObjectStore.SaveBytes($"{qb.ProjectId}/bytesKey", bytesSample)

save_successful = qb.ObjectStore.SaveBytes(f"{qb.ProjectId}/bytes_key", bytes_sample)

Strings

To save a string object, call the Save or SaveString method.

var saveSuccessful = qb.ObjectStore.Save($"{qb.ProjectId}/stringKey", stringSample);

save_successful = qb.ObjectStore.Save(f"{qb.ProjectId}/string_key", string_sample)

JSON

To save a JSON object, call the SaveJson<T> method. This method helps to serialize the data into JSON format.

var saveSuccessful = qb.ObjectStore.SaveJson<Dictionary<string, int>>($"{qb.ProjectId}/jsonKey", dictSample);

XML

To save an XML-formatted object, call the SaveXml<T> method.

var saveSuccessful = qb.ObjectStore.SaveXml<XElement>($"{qb.ProjectId}/xmlKey", xmlSample);

Read Data

To read data from the Object Store, you need to provide the key you used to store the object.

You can load the following types of objects from the Object Store:

• Bytes objects
• string objects
• JSON objects
• XML-formatted objects

You can load Bytes and string objects from the Object Store.

Before you read data from the Object Store, check if the key exists.

if (qb.ObjectStore.ContainsKey(key))
{
    // Read data
}

if qb.ObjectStore.ContainsKey(key):
    # Read data

Bytes

To read a Bytes object, call the ReadBytes method.

var bytesData = qb.ObjectStore.ReadBytes($"{qb.ProjectId}/bytesKey");

byte_data = qb.ObjectStore.ReadBytes(f"{qb.ProjectId}/bytes_key")

Strings

To read a string object, call the Read or ReadString method.

var stringData = qb.ObjectStore.Read($"{qb.ProjectId}/stringKey");

string_data = qb.ObjectStore.Read(f"{qb.ProjectId}/string_key")

JSON

To read a JSON object, call the ReadJson<T> method.

var jsonData = qb.ObjectStore.ReadJson<Dictionary<string, int>>($"{qb.ProjectId}/jsonKey");

XML

To read an XML-formatted object, call the ReadXml<T> method.

var xmlData = qb.ObjectStore.ReadXml<XElement>($"{qb.ProjectId}/xmlKey");

If you created the XML object from a dictionary, reconstruct the dictionary.

var dict = xmlData.Elements().ToDictionary(x => x.Name.LocalName, x => int.Parse(x.Value));

Delete Data

Delete objects in the Object Store to remove objects that you no longer need. If you use the Research Environment in QuantConnect Cloud, you need storage delete permissions to delete data from the Object Store.

To delete objects from the Object Store, call the Delete method. Before you delete data, check if the key exists. If you try to delete an object with a key that doesn't exist in the Object Store, the method raises an exception.

if (qb.ObjectStore.ContainsKey(key))
{
    qb.ObjectStore.Delete(key);
}

if qb.ObjectStore.ContainsKey(key):
    qb.ObjectStore.Delete(key)

To delete all of the content in the Object Store, iterate through all the stored data.

foreach (var kvp in qb.ObjectStore)
{
    qb.ObjectStore.Delete(kvp.Key);
}

for kvp in qb.ObjectStore:
    qb.ObjectStore.Delete(kvp.Key)

Cache Data

When you write to or read from the Object Store, the notebook caches the data. The cache speeds up the notebook execution because if you try to read the Object Store data again with the same key, it returns the cached data instead of downloading the data again. The cache speeds up execution, but it can cause problems if you are trying to share data between two nodes under the same Object Store key. For example, consider the following scenario:

1. You open project A and save data under the key 123 .
2. You open project B and save new data under the same key 123 .
3. In project A, you read the Object Store data under the key 123 , expecting the data from project B, but you get the original data you saved in step #1 instead.

You get the data from step 1 instead of step 2 because the cache contains the data from step 1.

To clear the cache, call the Clear method.

qb.ObjectStore.Clear();

qb.ObjectStore.Clear()

Get File Path

To get the file path for a specific key in the Object Store, call the GetFilePath method. If the key you pass to the method doesn't already exist in the Object Store, it's added to the Object Store.

var filePath = qb.ObjectStore.GetFilePath(key);

file_path = qb.ObjectStore.GetFilePath(key)

Storage Quotas

If you use the Research Environment locally, you can store as much data as your hardware will allow. If you use the Research Environment in QuantConnect Cloud, you must stay within your storage quota . If you need more storage space, edit your storage plan .

Example

You can use the ObjectStore to plot data from your backtests and live algorithm in the Research Environment. In the following example, you will learn how to plot the Simple Moving Average indicator generated in a backtest.

1. Create a algorithm, add a data subscription and a Simple Moving Average indicator.

public class ObjectStoreChartingAlgorithm : QCAlgorithm
{
    private SimpleMovingAverage _sma;
    private string _content;

    public override void Initialize()
    {
        AddEquity("SPY", Resolution.Minute);
        _sma = SMA("SPY", 22);
    }
}

class ObjectStoreChartingAlgorithm(QCAlgorithm):
    def Initialize(self):
        self.AddEquity("SPY")
    
        self.content = ''
        self.sma = self.SMA("SPY", 22)

The algorithm will save _content self.content to the ObjectStore .

2. Save indicator data as string in _content self.content .

public override void OnData(Slice data)
{
    _content += $"{_sma.Current.EndTime},{_sma}\n";
}

def OnData(self, data: Slice):
    self.Plot('SMA', 'Value', self.sma.Current.Value)
    self.content += f'{self.sma.Current.EndTime},{self.sma.Current.Value}\n'

3. To store the collected data, call the Save method with a key.

public override void OnEndOfAlgorithm()
{
    ObjectStore.Save("sma_values_csharp", _content);
}

def OnEndOfAlgorithm(self):
    self.ObjectStore.Save('sma_values_python', self.content)

4. Open the Research Environment, and create a QuantBook .

// Execute the following command in first
#load "../Initialize.csx"

// Create a QuantBook object
#load "../QuantConnect.csx"
using QuantConnect;
using QuantConnect.Research;

var qb = new QuantBook();

qb = QuantBook()

5. To read data from the Object Store, call the Read method. You need to provide the key you used to store the object.

var content = qb.ObjectStore.Read("sma_values_csharp");

content = qb.ObjectStore.Read("sma_values_python")

6. Convert the data to a pandas object, and create a chart.

data = {}
for line in content.split('\n'):
    csv = line.split(',')
    if len(csv) > 1:
        data[csv[0]] = float(csv[1])

series = pd.Series(data, index=data.keys())
series.plot()

7. Import the Plotly.NET and Plotly.NET.LayoutObjects packages.

#r "../Plotly.NET.dll"
using Plotly.NET;
using Plotly.NET.LayoutObjects;

8. Create the Layout object, and set the title , xaxis , and yaxis properties.

var layout = new Layout();
layout.SetValue("title", Title.init("SMA"));

var xAxis = new LinearAxis();
xAxis.SetValue("title", "Time");
layout.SetValue("xaxis", xAxis);

var yAxis = new LinearAxis();
yAxis.SetValue("title", "SMA");
layout.SetValue("yaxis", yAxis);

9. Convert the data to a list of DateTime objects for the chart x-axis and a list of decimal objects for the chart y-axis. Create a Chart2D.Chart.Line object with the data.

var index = new List<DateTimee>();
var values = new List<decimal>();

foreach (var line in content.Split('\n'))
{
    var csv = line.Split(',');
    if (csv.Length > 1)
    {
        index.Add(Parse.DateTime(csv[0]));
        values.Add(decimal.Parse(csv[1]));
    }
}

var chart = Chart2D.Chart.Linee<DateTime, decimal, stringe>(index, values);

10. Apply the layout to the Line object, and create the HTML object.

chart.WithLayout(layout);
var result = HTML(GenericChart.toChartHTML(chart));

Machine Learning

Machine Learning > Key Concepts

Introduction

Machine learning is a field of study that combines statistics and computer science to build intelligent systems that predict outcomes. Quant researchers commonly use machine learning models to optimize portfolios, make trading signals, and manage risk. These models can find relationships in datasets that humans struggle to find, are subtle, or are too complex. You can use machine learning techniques in your research notebooks.

Supported Libraries

The following table shows the supported machine learning libraries:

Add New Libraries

To request a new library, contact us . We will add the library to the queue for review and deployment. Since the libraries run on our servers, we need to ensure they are secure and won't cause harm. The process of adding new libraries takes 2-4 weeks to complete. View the list of libraries currently under review on the Issues list of the Lean GitHub repository .

Transfer Models

You can load machine learning models from the Object Store or a custom data file like pickle. If you train a model in the Research Environment, you can also save it into the Object Store to transfer it to the backtesting and live trading environment.

Machine Learning > Keras

Introduction

This page explains how to build, train, test, and store keras models.

Import Libraries

Import the keras libraries.

from tensorflow.keras import utils, models
from tensorflow.keras.models import Sequential
from tensorflow.keras.layers import Dense, Flatten
from tensorflow.keras.optimizers import RMSprop

Get Historical Data

Get some historical market data to train and test the model. For example, to get data for the SPY ETF during 2020 and 2021, run:

qb = QuantBook()
symbol = qb.AddEquity("SPY", Resolution.Daily).Symbol
history = qb.History(symbol, datetime(2020, 1, 1), datetime(2022, 1, 1)).loc[symbol]

Prepare Data

You need some historical data to prepare the data for the model. If you have historical data, manipulate it to train and test the model. In this example, use the following features and labels:

The following image shows the time difference between the features and labels:

Follow these steps to prepare the data:

1. Call the pct_change and dropna methods.

daily_pct_change = history.pct_change().dropna()

2. Loop through the daily_pct_change DataFrame and collect the features and labels.

n_steps = 5
features = []
labels = []
for i in range(len(daily_pct_change)-n_steps):
    features.append(daily_pct_change.iloc[i:i+n_steps].values)
    labels.append(daily_pct_change['close'].iloc[i+n_steps])

3. Convert the lists of features and labels into numpy arrays.

features = np.array(features)
labels = np.array(labels)

4. Split the data into training and testing periods.

train_length = int(len(features) * 0.7)
X_train = features[:train_length]
X_test = features[train_length:]
y_train = labels[:train_length]
y_test = labels[train_length:]

Train Models

You need to prepare the historical data for training before you train the model. If you have prepared the data, build and train the model. In this example, build a neural network model that predicts the future return of the SPY. Follow these steps to create the model:

1. Call the Sequential constructor with a list of layers.

model = Sequential([Dense(10, input_shape=(5,5), activation='relu'),
                    Dense(10, activation='relu'),
                    Flatten(),
                    Dense(1)])

Set the input_shape of the first layer to (5, 5) because each sample contains the percent change of 5 factors (percent change of the open, high, low, close, and volume) over the previous 5 days. Call the Flatten constructor because the input is 2-dimensional but the output is just a single value.

2. Call the compile method with a loss function, an optimizer, and a list of metrics to monitor.

model.compile(loss='mse',
              optimizer=RMSprop(0.001),
              metrics=['mae', 'mse'])

3. Call the fit method with the features and labels of the training dataset and a number of epochs.

model.fit(X_train, y_train, epochs=5)

Test Models

You need to build and train the model before you test its performance. If you have trained the model, test it on the out-of-sample data. Follow these steps to test the model:

1. Call the predict method with the features of the testing period.

y_hat = model.predict(X_test)

2. Plot the actual and predicted labels of the testing period.

results = pd.DataFrame({'y': y_test.flatten(), 'y_hat': y_hat.flatten()})
df.plot(title='Model Performance: predicted vs actual %change in closing price')

Store Models

You can save and load keras models using the ObjectStore.

Save Models

Follow these steps to save models in the ObjectStore:

1. Set the key name of the model to be stored in the ObjectStore.

model_key = "model"

2. Call the GetFilePath method with the key.

file_name = qb.ObjectStore.GetFilePath(model_key)

This method returns the file path where the model will be stored.

3. Call the save method the file path.

model.save(file_name)

Load Models

You must save a model into the ObjectStore before you can load it from the ObjectStore. If you saved a model, follow these steps to load it:

1. Call the ContainsKey method with the model key.

qb.ObjectStore.ContainsKey(model_key)

This method returns a boolean that represents if the model_key is in the ObjectStore. If the ObjectStore does not contain the model_key , save the model using the model_key before you proceed.

2. Call the GetFilePath method with the key name.

file_name = qb.ObjectStore.GetFilePath(model_key)

This method returns the path where the model is stored.

3. Call the load_model method with the file path.

loaded_model = load_model(file_name)

This method returns the saved model.

Machine Learning > TensorFlow

Introduction

This page explains how to build, train, test, and store Tensorflow models.

Import Libraries

Import the tensorflow , sklearn , json5 and google.protobuf libraries.

import tensorflow as tf
from sklearn.model_selection import train_test_split
import json5
from google.protobuf import json_format

You need the sklearn library to prepare the data and the json5 and google.protobuf libraries to save models.

Get Historical Data

Get some historical market data to train and test the model. For example, to get data for the SPY ETF during 2020 and 2021, run:

qb = QuantBook()
symbol = qb.AddEquity("SPY", Resolution.Daily).Symbol
history = qb.History(symbol, datetime(2020, 1, 1), datetime(2022, 1, 1)).loc[symbol]

Prepare Data

You need some historical data to prepare the data for the model. If you have historical data, manipulate it to train and test the model. In this example, use the following features and labels:

Follow these steps to prepare the data:

1. Loop through the DataFrame of historical prices and collect the features.

lookback = 5
lookback_series = []
for i in range(1, lookback + 1):
    df = history['close'].shift(i)[lookback:-1]
    df.name = f"close_-{i}"
    lookback_series.append(df)
X = pd.concat(lookback_series, axis=1).reset_index(drop=True)

The following image shows the format of the features DataFrame:


2. Select the close column and then call the shift method to collect the labels.

Y = history['close'].shift(-1)

3. Drop the first 5 features and then call the reset_index method.

Y = Y[lookback:-1].reset_index(drop=True)

This method aligns the history of the features and labels.

4. Call the train_text_split method with the datasets and a split size.

For example, to use the last third of data to test the model, run:

X_train, X_test, y_train, y_test = train_test_split(X, Y, test_size=0.33, shuffle=False)

Train Models

You need to prepare the historical data for training before you train the model. If you have prepared the data, build and train the model. In this example, build a neural network model that predicts the future price of the SPY.

Build the Model

Follow these steps to build the model:

1. Call the reset_default_graph method.

tf.reset_default_graph()

This method clears the default graph stack and resets the global default graph.

2. Call the Session constructor.

sess = tf.Session()

3. Declare the number of factors and then create placeholders for the input and output layers.

num_factors = X_test.shape[1]
X = tf.placeholder(dtype=tf.float32, shape=[None, num_factors], name='X')
Y = tf.placeholder(dtype=tf.float32, shape=[None])

4. Set up the weights and bias initializers for each layer.

weight_initializer = tf.variance_scaling_initializer(mode="fan_avg", distribution="uniform", scale=1)
bias_initializer = tf.zeros_initializer()

5. Create hidden layers that use the Relu activator.

num_neurons_1 = 32
num_neurons_2 = 16
num_neurons_3 = 8

W_hidden_1 = tf.Variable(weight_initializer([num_factors, num_neurons_1]))
bias_hidden_1 = tf.Variable(bias_initializer([num_neurons_1]))
hidden_1 = tf.nn.relu(tf.add(tf.matmul(X, W_hidden_1), bias_hidden_1))

W_hidden_2 = tf.Variable(weight_initializer([num_neurons_1, num_neurons_2]))
bias_hidden_2 = tf.Variable(bias_initializer([num_neurons_2]))
hidden_2 = tf.nn.relu(tf.add(tf.matmul(hidden_1, W_hidden_2), bias_hidden_2))

W_hidden_3 = tf.Variable(weight_initializer([num_neurons_2, num_neurons_3]))
bias_hidden_3 = tf.Variable(bias_initializer([num_neurons_3]))
hidden_3 = tf.nn.relu(tf.add(tf.matmul(hidden_2, W_hidden_3), bias_hidden_3))

6. Create the output layer and give it a name.

W_out = tf.Variable(weight_initializer([num_neurons_3, 1]))
bias_out = tf.Variable(bias_initializer([1]))
output = tf.transpose(tf.add(tf.matmul(hidden_3, W_out), bias_out), name='outer')

This snippet creates a 1-node output for both weight and bias. You must name the output layer so you can access it after you load and save the model.

7. Set up the loss function and optimizers for gradient descent optimization and backpropagation.

loss = tf.reduce_mean(tf.squared_difference(output, Y))
optimizer = tf.train.AdamOptimizer().minimize(loss)

Use mean-square error as the loss function because the close price is a continuous data and use Adam as the optimizer because of its adaptive step size.

8. Set the batch size and number of epochs to bootstrap the training process.

batch_size = len(y_train) // 10
epochs = 20

Train the Model

Follow these steps to train the model:

1. Call the run method with the result from the global_variables_initializer method.

sess.run(tf.global_variables_initializer())

2. Loop through the number of epochs, select a subset of the training data, and then call the run method with the subset of data.

for _ in range(epochs):
    for i in range(0, len(y_train) // batch_size):
        start = i * batch_size
        batch_x = X_train[start:start + batch_size]
        batch_y = y_train[start:start + batch_size]
        sess.run(optimizer, feed_dict={X: batch_x, Y: batch_y})

Test Models

To test the model, we'll setup a method to plot test set predictions ontop of the SPY price.

def test_model(sess, output, title, X):
    prediction = sess.run(output, feed_dict={X: X_test})
    prediction = prediction.reshape(prediction.shape[1], 1)

    y_test.reset_index(drop=True).plot(figsize=(16, 6), label="Actual")
    plt.plot(prediction, label="Prediction")
    plt.title(title)
    plt.xlabel("Time step")
    plt.ylabel("SPY Price")
    plt.legend()
    plt.show()

test_model(sess, output, "Test Set Results from Original Model", X)

Store Models

You can save and load TensorFlow models using the ObjectStore.

Save Models

Follow these steps to save models in the ObjectStore:

1. Export the TensorFlow graph as a JSON object.

graph_definition = tf.compat.v1.train.export_meta_graph()
json_graph = json_format.MessageToJson(graph_definition)

2. Export the TensorFlow weights as a JSON object.

# Define a function to get the weights from the tensorflow session
def get_json_weights(sess):
    weights = sess.run(tf.compat.v1.trainable_variables())
    weights = [w.tolist() for w in weights]
    weights_list = json5.dumps(weights)
    return weights_list
    
json_weights = get_json_weights(sess)
sess.close()    # Close the session opened by the `get_json_weights` function

3. Save the graph and weights to the ObjectStore .

qb.ObjectStore.Save('graph', json_graph)
qb.ObjectStore.Save('weights', json_weights)

Load Models

You must save a model into the ObjectStore before you can load it from the ObjectStore. If you saved a model, follow these steps to load it:

1. Read the model graph and weights from the ObjectStore .

json_graph = qb.ObjectStore.Read('graph')
json_weights = qb.ObjectStore.Read('weights')

2. Restore the TensorFlow graph from the JSON object.

tf.reset_default_graph()
graph_definition = json_format.Parse(json_graph, tf.compat.v1.MetaGraphDef())
sess = tf.Session()
tf.compat.v1.train.import_meta_graph(graph_definition)

3. Select the input and output tensors.
   

X = tf.compat.v1.get_default_graph().get_tensor_by_name('X:0')
output = tf.compat.v1.get_default_graph().get_tensor_by_name('outer:0')

4. Restore the model weights from the JSON object.

weights = [np.asarray(x) for x in json5.loads(json_weights)]
assign_ops = []
feed_dict = {}
vs = tf.compat.v1.trainable_variables()
zipped_values = zip(vs, weights)
for var, value in zipped_values:
    value = np.asarray(value)
    assign_placeholder = tf.placeholder(var.dtype, shape=value.shape)
    assign_op = var.assign(assign_placeholder)
    assign_ops.append(assign_op)
    feed_dict[assign_placeholder] = value
sess.run(assign_ops, feed_dict=feed_dict)

Machine Learning > Scikit-Learn

Introduction

This page explains how to build, train, test, and store Scikit-Learn / sklearn models.

Import Libraries

Import the sklearn libraries.

from sklearn.svm import SVR
from sklearn.model_selection import GridSearchCV
from sklearn.model_selection import train_test_split
import joblib

You need the joblib library to store models.